# Velvet Rituals developer docs (full) Source: https://developer.velvetrituals.com/docs/ (index: https://developer.velvetrituals.com/llms.txt) --- # Quickstart Make a Velvet toy (or the virtual toy) buzz from your own web page in about ten minutes. Using Claude, Cursor or Copilot? [Connect our docs](https://developer.velvetrituals.com/docs/ai-tools.md) so your assistant writes working Velvet code. ## 1. Get a test key 1. [Sign up](https://developer.velvetrituals.com/signup/) or [log in](https://developer.velvetrituals.com/login/) with your Velvet account. 2. On the [dashboard](https://developer.velvetrituals.com/dashboard/), create your test app: a name, one line on what you're building, the 18+ check and the [developer terms](https://developer.velvetrituals.com/terms/). 3. Copy the **publishable key** (`vr_pk_test_…`). It's shown once. A test key works on `localhost` with no setup. To use it on a real domain, add the domain under **Allowed origins**. ## 2. Add the SDK Install it from npm: ```bash npm install @velvetrituals/toys ``` Or, with no build step, load it with a ` ``` Pin the version in the URL, as above, so an SDK release never changes your page without you knowing. ## 3. Connect and vibrate **JavaScript** ```ts import { VelvetToys } from '@velvetrituals/toys'; // Verifies your key once at start-up. const velvet = await VelvetToys.init({ apiKey: 'vr_pk_test_…', // Dev only: point at the dev gateway. Leave it out in production. baseUrl: 'https://devgateway-api.thinkbeyondcorporate.com/v1', }); let toy; // Must run inside a click handler: the browser opens its Bluetooth picker. connectButton.onclick = async () => { toy = await velvet.connect(); await toy.vibrate({ strength: 70, durationMs: 3000 }); }; stopButton.onclick = () => toy?.stop(); // always give players a Stop button ``` **Script tag** ```html ``` **React** ```tsx 'use client'; // Next.js: the SDK runs in the browser only import { VelvetToys, type Toy } from '@velvetrituals/toys'; import { useEffect, useRef, useState } from 'react'; export function BuzzButton() { const velvet = useRef(null); const [toy, setToy] = useState(null); // Verify the key once, before any click, so connect() keeps the user gesture. useEffect(() => { VelvetToys.init({ apiKey: 'vr_pk_test_…' }).then((v) => (velvet.current = v)); return () => void velvet.current?.destroy(); // stops and disconnects the toy }, []); if (!toy) { return ; } return ( <> ); } ``` No toy to hand? Use the virtual toy. Same API, same limits, no Bluetooth: ```ts import { mountVirtualToyWidget } from '@velvetrituals/toys'; const toy = await velvet.connect({ virtual: true, model: 'Eclipse' }); mountVirtualToyWidget(document.querySelector('#toy'), toy); ``` ## 4. Serve it on localhost Web Bluetooth needs a secure context, and `http://localhost` counts. Any static server works: ```bash npx serve . ``` Before connecting a real toy, close Velvet Vibes on your phone or disconnect the toy there. A toy talks to one app at a time. ## Next - See it all working in [Card Vibe](https://developer.velvetrituals.com/demo/card-vibe/). - [SDK reference](https://developer.velvetrituals.com/docs/sdk.md) for every call. - [Safety](https://developer.velvetrituals.com/docs/safety.md) for what the SDK enforces, and what you must do. --- # Keys Every app has publishable and secret keys, Stripe-style. Manage them on the [dashboard](https://developer.velvetrituals.com/dashboard/). | Key | Prefix | Where it goes | Checked by | | --- | --- | --- | --- | | Publishable | `vr_pk_test_` / `vr_pk_live_` | Your web page or app. Public. | The SDK, at `init()` and every `connect()` | | Secret | `vr_sk_test_` / `vr_sk_live_` | Your server only. Never in a page or app. | Velvet server APIs (none public in v1) | ## Test and live - **Test keys** are instant. You need a full (non-guest) Velvet account, to be 18 or older, to accept the [terms](https://developer.velvetrituals.com/terms/), and to say in one line what you're building. One test app per account. - **Live keys** are for public apps. Request them from the dashboard; we review each app by hand. Once approved, the app turns live and you create live keys from the Keys card. ## Allowed origins A publishable key only works where you allow it: up to **3** domains (`example.com`) or mobile app IDs (`com.example.app`). The browser's `Origin` is what's checked, so another site can't use your key. `localhost` always works for test keys. ## Shown once We store a hash of each key, plus its prefix and last four characters. The full key is shown **once**, when it's created. If you lose it, rotate it. ## Rotate and revoke - **Rotate** gives you a new key of the same kind. The old one keeps working for **24 hours**, so you can deploy without downtime. - **Revoke** stops a key at once. Apps that use it fail at their next `init()` or `connect()`. ## What the key check sends The SDK sends your key, the SDK version and (from the browser) your page's origin. Nothing about your players. The reply is your app's status and limits: ```json { "data": { "appId": "…", "environment": "test", "status": "active", "limits": { "maxStrength": 100, "maxDurationMs": 60000 } } } ``` A suspended app gets `status: "suspended"`, and the SDK refuses to run. An unknown, revoked or expired key gets `401 invalid_key`. --- # SDK reference `@velvetrituals/toys` (web, v0.1). Strength is always **0–100**. Every command has a duration and stops on its own. ## `VelvetToys.init(options)` ```ts const velvet = await VelvetToys.init({ apiKey: 'vr_pk_test_…', // publishable key; a secret key is refused backgroundPlayback: false, // true = keep playing while the page is hidden baseUrl: undefined, // gateway override, e.g. the dev gateway debug: false, // log protocol traffic to the console }); ``` Verifies the key and returns a client. It throws a `VelvetToysError` if the key is invalid, revoked or expired, the origin isn't allowed, or the app is suspended. Only `active` results are cached, for at most an hour, and only used when the network fails. | Property | Meaning | | --- | --- | | `velvet.appId` | Your app's ID | | `velvet.environment` | `'test'` or `'live'` | | `velvet.limits` | `{ maxStrength, maxDurationMs }`. Every command is clamped to these | | `velvet.connectedToys` | Toys connected through this client | ## `velvet.connect(options?)` ```ts const toy = await velvet.connect(); // Bluetooth picker const sim = await velvet.connect({ virtual: true, model: 'Eclipse' }); // virtual toy ``` Call it from a click handler: the browser only opens its picker on a user gesture. The key is checked again on every call. Picking a toy that's already connected returns the same `Toy`. `velvet.destroy()` stops and disconnects every toy. ## Toy commands | Call | Rules | | --- | --- | | `toy.vibrate({ strength, durationMs, motor? })` | `strength` 0–100. `durationMs` 100–60,000, required. `motor` 1 (outer), 2 (insertable) or `'all'` (default); 1 and 2 only on dual-motor toys | | `toy.preset({ name, strength, durationMs })` | A built-in firmware mode (below); strength and duration as for vibrate | | `toy.pattern({ steps, loop?, durationMs, motor? })` | Up to 50 steps of `{ strength, ms }`, each at least 100 ms. With `loop`, repeats until `durationMs` | | `toy.playTrack(track, { media?, offsetMs?, motor? })` | Plays a strength curve, following a `