@volter/twin-twilio 0.1.0 → 0.1.2

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

@@ -88,7 +88,7 @@
 // `phone_number:<sid>`) — the PUBLIC sid emitted to clients is the bare Twilio-shaped sid
 // (SM…/VE…/PN…). `kid()` builds the subject id; `rows()` strips the prefix back off.
 import { createHash } from 'node:crypto';
-import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { presentedTwilioCredentials, storedTwilioCredentials, twilioCredentials } from "./twilio-credentials.js";
 const SERVICE = 'twilio';
 const API_VERSION = '2010-04-01';
@@ -150,7 +150,7 @@ function parseFormBody(body) {
     return { ok: true, value };
 }
 function nowIso(occurredAt) {
-    return occurredAt ?? new Date().toISOString();
+    return occurredAt ?? worldNow();
 }
 /** Twilio's own message/account timestamp wire format (RFC 2822-ish, e.g. "Fri, 24 May 2019
  *  17:44:46 +0000") — grounded from the twilio_api_v2010.json Messages-list example AND the
@@ -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.0",
+  "version": "0.1.2",
   "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.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@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

@@ -88,7 +88,7 @@
 // `phone_number:<sid>`) — the PUBLIC sid emitted to clients is the bare Twilio-shaped sid
 // (SM…/VE…/PN…). `kid()` builds the subject id; `rows()` strips the prefix back off.
 import { createHash } from 'node:crypto';
-import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/world-core';
 import { presentedTwilioCredentials, storedTwilioCredentials, twilioCredentials } from './twilio-credentials.ts';
 
 const SERVICE = 'twilio';
@@ -175,7 +175,7 @@ function parseFormBody(body?: string): { ok: true; value: Record<string, string>
 }
 
 function nowIso(occurredAt?: string): string {
-  return occurredAt ?? new Date().toISOString();
+  return occurredAt ?? worldNow();
 }
 /** Twilio's own message/account timestamp wire format (RFC 2822-ish, e.g. "Fri, 24 May 2019
  *  17:44:46 +0000") — grounded from the twilio_api_v2010.json Messages-list example AND the
@@ -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) } };
 }