Merge pull request #15 from photon-hq/docs/update-spectrum-ts-v1.3.0

docs: update spectrum-ts documentation for v1.3.0

Author: underthestars-zhy

docs-src/spectrum-ts/custom-events-and-lifecycle.mdx.vel

@@ -42,7 +42,7 @@ Use the flat form on `app` when you want a merged feed across platforms; use the
 await app.stop();
 ```
 
-This closes the merged message stream, drains and disposes every custom event stream, and tears down every platform client via its `lifecycle.destroyClient` hook. It's idempotent — calling `stop()` twice is safe.
+This closes the merged message stream, drains and disposes every custom event stream, and tears down every platform client via its `lifecycle.destroyClient` hook (if one is defined). It's idempotent — calling `stop()` twice is safe.
 
 ### Signal handling
 

docs-src/spectrum-ts/custom-platforms.mdx.vel

@@ -46,7 +46,7 @@ export const myPlatform = definePlatform("my-platform", {
 
   // Client lifecycle
   lifecycle: {
-    createClient: async ({ config }) => new MyPlatformClient(config.apiKey),
+    createClient: async ({ config, store }) => new MyPlatformClient(config.apiKey),
     destroyClient: async ({ client }) => { await client.disconnect(); },
   },
 
@@ -93,8 +93,8 @@ export const myPlatform = definePlatform("my-platform", {
 | `space.resolve` | Yes | Resolves or creates a conversation. Receives an array of users plus optional params. |
 | `space.schema` | No | Optional Zod schema for the resolved space. |
 | `space.params` | No | Zod schema for additional space creation parameters — surfaces as the second arg to `platform(app).space()`. |
-| `lifecycle.createClient` | Yes | Creates the platform client. Receives `config`, `projectId`, `projectSecret` (both may be `undefined`). |
-| `lifecycle.destroyClient` | Yes | Tears down the client on shutdown. |
+| `lifecycle.createClient` | Yes | Creates the platform client. Receives `config`, `projectId`, `projectSecret` (both may be `undefined`), and `store`. |
+| `lifecycle.destroyClient` | No | Tears down the client on shutdown. Omit if no cleanup is needed. |
 | `events.messages` | Yes | Async generator that yields incoming messages. |
 | `events.[custom]` | No | Additional async generators for platform-specific events — exposed on `app.[eventName]`. |
 | `actions.send` | Yes | Sends a single content item to a space. Invoked once per item when multiple are passed. |
@@ -107,7 +107,7 @@ export const myPlatform = definePlatform("my-platform", {
 
 ## Event producers
 
-Every event generator receives `{ client, config }` and returns an `AsyncIterable`. The signature is <TypeTooltip name="EventProducer" type={`{{ ep.signature }}`} />.
+Every event generator receives `{ client, config, store }` and returns an `AsyncIterable`. The signature is <TypeTooltip name="EventProducer" type={`{{ ep.signature }}`} />.
 
 ```ts
 events: {

docs-src/spectrum-ts/providers/imessage.mdx.vel

@@ -7,7 +7,7 @@ description: "Receive and send iMessage across local, cloud, and dedicated modes
 import { imessage } from "spectrum-ts/providers/imessage";
 ```
 
-The iMessage provider supports three connection modes — local, cloud, and dedicated — and exposes iMessage-specific features (tapbacks, DM vs group spaces) through [platform narrowing](/spectrum-ts/platform-narrowing).
+The iMessage provider supports three connection modes — local, cloud, and dedicated — and exposes iMessage-specific features (tapbacks, DM vs group spaces, per-phone routing) through [platform narrowing](/spectrum-ts/platform-narrowing).
 
 ## Connection modes
 
@@ -41,18 +41,18 @@ The iMessage provider supports three connection modes — local, cloud, and dedi
     </Note>
   </Tab>
   <Tab title="Dedicated">
-    Connect directly to one or more iMessage gRPC endpoints with your own tokens — use this when you're running your own iMessage relay and want to skip cloud auth:
+    Connect directly to one or more iMessage gRPC endpoints with your own tokens — use this when you're running your own iMessage relay and want to skip cloud auth. Each entry must include the `phone` number the instance serves, so Spectrum can route messages through the right number:
 
     ```ts
     imessage.config({
       clients: [
-        { address: "instance-1.example.com:443", token: "your-token" },
-        { address: "instance-2.example.com:443", token: "your-token" },
+        { address: "instance-1.example.com:443", token: "your-token", phone: "+15551111111" },
+        { address: "instance-2.example.com:443", token: "your-token", phone: "+15552222222" },
       ],
     });
     ```
 
-    Multiple clients load-balance across instances.
+    Multiple clients route messages based on the phone number associated with each space.
   </Tab>
 </Tabs>
 
@@ -66,6 +66,7 @@ Cloud mode routes your messages through phone numbers ("lines") provisioned by S
 | **Business** | **Dedicated.** All of your end users text the same number, which belongs to your project. | A normal iMessage, always from the same number. |
 
 End-user delivery is identical in both modes; the distinction is which number sends.
+Cloud mode routes your messages through dedicated phone numbers ("lines") provisioned by Spectrum. Each project gets one or more dedicated lines, and all your end users text the same number(s).
 
 ### Auto-scale
 
@@ -77,12 +78,13 @@ When traffic to a dedicated line approaches its per-line capacity, Spectrum can
 
 ## Space types
 
-iMessage spaces carry a `type` field — `"dm"` or `"group"` — accessible through narrowing:
+iMessage spaces carry a `type` field — `"dm"` or `"group"` — and a `phone` field indicating which phone number the conversation is routed through. Both are accessible through narrowing:
 
 ```ts
 for await (const [space, message] of app.messages) {
   if (message.platform !== "iMessage") continue;
   const im = imessage(space);
+  console.log(im.phone); // the phone number handling this conversation
   if (im.type === "group") {
     // group chat logic
   }
@@ -109,6 +111,16 @@ await group.send("Welcome to the group.");
 
 Space creation requires cloud or dedicated mode. In local mode `space()` throws — the local Messages database doesn't expose chat creation.
 
+### Per-phone routing
+
+If your account has multiple phone numbers, you can pin a conversation to a specific line by passing `phone` as a space parameter:
+
+```ts
+const dm = await im.space(alice, { phone: "+15559999999" });
+```
+
+When omitted, Spectrum picks a phone at random from the available lines. All subsequent actions on that space — sending, typing, replies, edits, reactions, and lookups — route through the chosen number.
+
 ## Tapback constants
 
 iMessage uses a fixed set of tapback reactions. The `imessage` object exposes them as constants:

package.json

@@ -27,7 +27,7 @@
     "eslint-plugin-format": "^2.0.1",
     "husky": "^9.1.7",
     "oxfmt": "^0.44.0",
-    "spectrum-ts": "^0.3.0",
+    "spectrum-ts": "1.2.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }