@volter/twin-twilio 0.1.1 → 0.1.3

package/dist/src/twilio-server.js

@@ -24,12 +24,14 @@
 // a genuinely empty response. The server is one line of Bun.serve around that same closure.
 import { serveHttp } from '@volter/world-core';
 import { handleTwilioTwinRequest } from "./twilio-twin.js";
-import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+import { createTwinFetchFromHandler, statefulTwinManifest, withRequestScopes } from '@volter/world-core';
 export function createTwilioTwinFetch(options = {}) {
-    return createTwinFetchFromHandler(handleTwilioTwinRequest, {
+    // a read-only request (x-volter-read-only) is a request to a read-only twin: a virgin World is not
+    // seeded with the presented credentials, nothing is sent (withRequestScopes: the pack opts in)
+    return withRequestScopes(createTwinFetchFromHandler(handleTwilioTwinRequest, {
         ...options,
         manifest: statefulTwinManifest({ vendor: 'twilio', twinOf: 'the Twilio messaging API', stores: 'sent messages progressing queued→sending→sent→delivered, with signed status callbacks' }),
-    });
+    }));
 }
 export async function createTwilioTwinServer(options = {}) {
     const server = await serveHttp({

package/dist/src/twilio-twin.js

@@ -307,7 +307,10 @@ async function handleMessageGet(accountSid, sid, req) {
     const existing = getRow('message', sid, req.root);
     if (!existing)
         return notFound();
-    await progressMessageOnce(sid, req);
+    // ADVANCE ON POLL — a read-only twin (a World's read token) answers the message's current status and
+    // never advances it: the app's next poll sees exactly what it would have without the viewer.
+    if (!req.readOnly)
+        await progressMessageOnce(sid, req);
     const row = getRow('message', sid, req.root);
     return { status: 200, body: { ...sidView(row), ...messageUrls(accountSid, sid) } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-twilio",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local Twilio twin for the messaging/telephony surface (Messages send + delivery-status lifecycle, Verify start/check, Lookup, IncomingPhoneNumbers, X-Twilio-Signature-signed webhooks) built on @volter/world-core.",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
@@ -35,12 +35,12 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.1"
+    "@volter/world-core": "2.0.3"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/world-core": "2.0.1",
+    "@volter/world-core": "2.0.3",
     "@volter/world-tooling": "0.1.0",
     "twilio": "6.0.2",
     "typescript": "^5.9.0"

package/src/twilio-server.ts

@@ -24,7 +24,7 @@
 // a genuinely empty response. The server is one line of Bun.serve around that same closure.
 import { serveHttp } from '@volter/world-core';
 import { handleTwilioTwinRequest } from './twilio-twin.ts';
-import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+import { createTwinFetchFromHandler, statefulTwinManifest, withRequestScopes } from '@volter/world-core';
 
 /** Options every Twilio-twin HTTP surface needs, independent of who owns the socket. */
 export interface TwilioTwinFetchOptions {
@@ -33,10 +33,12 @@ export interface TwilioTwinFetchOptions {
 }
 
 export function createTwilioTwinFetch(options: TwilioTwinFetchOptions = {}): (request: Request) => Promise<Response> {
-  return createTwinFetchFromHandler(handleTwilioTwinRequest, {
+  // a read-only request (x-volter-read-only) is a request to a read-only twin: a virgin World is not
+  // seeded with the presented credentials, nothing is sent (withRequestScopes: the pack opts in)
+  return withRequestScopes(createTwinFetchFromHandler(handleTwilioTwinRequest, {
     ...options,
     manifest: statefulTwinManifest({ vendor: 'twilio', twinOf: 'the Twilio messaging API', stores: 'sent messages progressing queued→sending→sent→delivered, with signed status callbacks' }),
-  });
+  }));
 }
 
 export async function createTwilioTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {

package/src/twilio-twin.ts

@@ -345,7 +345,9 @@ async function progressMessageOnce(sid: string, req: TwilioRequest): Promise<voi
 async function handleMessageGet(accountSid: string, sid: string, req: TwilioRequest): Promise<TwilioResponse> {
   const existing = getRow('message', sid, req.root);
   if (!existing) return notFound();
-  await progressMessageOnce(sid, req);
+  // ADVANCE ON POLL — a read-only twin (a World's read token) answers the message's current status and
+  // never advances it: the app's next poll sees exactly what it would have without the viewer.
+  if (!req.readOnly) await progressMessageOnce(sid, req);
   const row = getRow('message', sid, req.root)!;
   return { status: 200, body: { ...sidView(row), ...messageUrls(accountSid, sid) } };
 }