@volter/twin-segment 0.1.0

package/dist/src/segment-server.js

@@ -0,0 +1,90 @@
+import { serveHttp } from '@volter/world-core';
+import { dropped, events, groups, handleSegmentTwinRequest, identities } from "./segment-twin.js";
+import { statefulTwinManifest, worldNow } from '@volter/world-core';
+/** The keyless discovery door's body: a frozen VALUE, built once at module load from
+ *  constants only. Nothing here reads the clock or state, so every serve of GET /twin is
+ *  byte-identical (serve-path determinism, R9). */
+const BASE_MANIFEST = statefulTwinManifest({
+    vendor: 'segment',
+    twinOf: 'the Segment HTTP Tracking API',
+    stores: 'tracked events, identify calls, group calls and refused (dropped) messages',
+    identity: 'Authenticate as Segment does — the write key as HTTP Basic username, an OAuth bearer, or `writeKey` in the body; the twin accepts any non-sentinel credential.',
+});
+/** THE STORE DOOR's projections (R5c). The Segment HTTP Tracking API is WRITE-ONLY — every route
+ *  is an ingest and none of them reads a message back — so these four named projections are the
+ *  only way to observe what was accepted, and `dropped` is the only way to see what was
+ *  accepted-and-refused (Segment answers 200 and silently drops; this twin records the reason).
+ *  They are also what makes this pack's determinism checkable at the resource level rather than
+ *  only at the manifest door. */
+const STORES = { events, identities, groups, dropped };
+const STORE_NAMES = Object.keys(STORES).sort();
+/** The manifest EDUCATES: it names the store door the way the kernel adapter does. */
+const MANIFEST = {
+    ...BASE_MANIFEST,
+    stores: STORE_NAMES,
+    doors: { ...BASE_MANIFEST.doors, store: 'GET /twin/store/<name>' },
+};
+/** The twin's HTTP face. Two things it must get right, both invisible to an in-process verify:
+ *  1. THE AUTHORIZATION HEADER IS PART OF THE PAYLOAD on this vendor. Two of Segment's three
+ *     documented auth schemes live in that header (Basic with the write key as the username;
+ *     OAuth Bearer), so a fetch that dropped it would make an analytics-node v1 client — which
+ *     sends `auth: { username: writeKey }` and NO writeKey in the body — arrive anonymous.
+ *  2. An empty-body status must serve a genuinely EMPTY body: `Response.json(null)` puts the
+ *     four bytes "null" on the wire (the A3-caught serialization class in
+ *     var/line/mixpanel/REVIEW.md).
+ *
+ *  FETCH-FIRST (runtime contract R12b): this is the pack's whole HTTP surface as a plain fetch,
+ *  and `createSegmentTwinServer` is one line of `Bun.serve` around it. It is a CUSTOM fetch, not
+ *  the kernel adapter (`createTwinFetchFromHandler`): the authorization threading (1) and the
+ *  handler-throw guard (below) are this pack's own. The keyless `GET /twin` manifest door the
+ *  adapter would have provided is mounted here by hand, answering the same
+ *  `statefulTwinManifest` shape — discovery is a door every twin owes (serve-path determinism
+ *  R9 replays it), and `/twin` shadows no Segment route: the Tracking API lives under `/v1/*`. */
+export function createSegmentTwinFetch(options = {}) {
+    return async function segmentTwinFetch(request) {
+        try {
+            const url = new URL(request.url);
+            const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+            // The keyless discovery door, before any vendor dispatch: a pure function of the
+            // manifest VALUE — no clock, no state — so replaying it is byte-identical (R9).
+            if (request.method === 'GET' && cleanPath === '/twin') {
+                return Response.json(MANIFEST);
+            }
+            // THE STORE DOOR (R5c) — see STORES above. Read-only, deterministic, served by the same
+            // fetch the vendor paths come out of; `/twin/*` shadows no Segment route (`/v1/*`).
+            if (request.method === 'GET' && cleanPath.startsWith('/twin/store/')) {
+                const name = cleanPath.slice('/twin/store/'.length);
+                const store = STORES[name];
+                if (!store)
+                    return Response.json({ error: 'unknown store', store: name, stores: STORE_NAMES }, { status: 404 });
+                return Response.json(store(options.root));
+            }
+            const res = await handleSegmentTwinRequest({
+                method: request.method,
+                path: url.pathname + url.search,
+                body: request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.text(),
+                contentType: request.headers.get('content-type') ?? undefined,
+                authorization: request.headers.get('authorization') ?? undefined,
+                // The WORLD instant (R9): `receivedAt` and every minted messageId come from the world
+                // clock, never wall time.
+                occurredAt: worldNow(),
+                root: options.root,
+            });
+            if (res.body === null || res.body === undefined)
+                return new Response(null, { status: res.status, headers: res.headers });
+            return Response.json(res.body, { status: res.status, headers: res.headers });
+        }
+        catch (err) {
+            // Never let a handler throw escape the fetch callback: under `bun test` that is reported as
+            // "unhandled between tests" and can stop later test registration, hiding the real defect
+            // (ADDING_A_TWIN §8). Answer the vendor's own error SHAPE.
+            return Response.json({ code: 'twin_internal_error', message: String(err) }, { status: 500 });
+        }
+    };
+}
+export async function createSegmentTwinServer(options = {}) {
+    return await serveHttp({
+        port: options.port ?? 0,
+        fetch: createSegmentTwinFetch(options),
+    });
+}

package/dist/src/segment-surface.gen.d.ts

@@ -0,0 +1,48 @@
+export type TwinOp = {
+    id: string;
+    area: string;
+    method: string;
+    path: string;
+    summary: string;
+    pathParams: string[];
+    requiredQuery: string[];
+    requiredBody: string[];
+    successStatus: number;
+    responseSkeleton: unknown;
+    specFile: string;
+    evidence: string;
+    tier: string;
+};
+export declare const OPS: TwinOp[];
+export type TwinRequest = {
+    method: string;
+    path: string;
+    body?: string;
+};
+export type TwinResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export type OpHandler = (ctx: {
+    op: TwinOp;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    body: unknown;
+    root?: string;
+}) => TwinResponse | Promise<TwinResponse>;
+/** Match one request against the ratified surface. PURE LOOKUP — dispatch belongs to the pack. */
+export declare function matchOp(req: TwinRequest): {
+    op: TwinOp;
+    params: Record<string, string>;
+    query: URLSearchParams;
+} | undefined;
+/** First required query/body field missing, or undefined (empty for sdk-ratified surfaces —
+ *  validation truth lives in the pack's semantics, grounded per op). */
+export declare function missingRequired(op: TwinOp, query: URLSearchParams, body: unknown): string | undefined;
+/** SCAFFOLD default error body — the A2 station replaces this with the vendor's REAL envelope. */
+export declare const errorBody: (message: string, field?: string) => {
+    field?: string | undefined;
+    success: boolean;
+    message: string;
+};

package/dist/src/segment-surface.gen.js

@@ -0,0 +1,267 @@
+// GENERATED by scripts/sdk-compile.ts from var/line/segment/SURFACE.json — the vendor
+// publishes no machine-readable spec; every op below carries the evidence it was ratified on.
+// Data only; regenerate, never hand-edit.
+export const OPS = [
+    {
+        "id": "alias",
+        "area": "alias",
+        "method": "POST",
+        "path": "/v1/alias",
+        "summary": "associate one identity with another: a `previousId` (userId or anonymousId) is aliased onto a new `userId`",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Alias' declares `POST https://api.segment.io/v1/alias` with a worked body {previousId, userId, timestamp, writeKey} and a field table naming previousId. Absent from @segment/analytics-node@2's wire surface (batched as type:'alias'); the SDK's AliasParams (src/app/types/params.ts) requires both userId and previousId.",
+        "tier": "common"
+    },
+    {
+        "id": "batch",
+        "area": "batch",
+        "method": "POST",
+        "path": "/v1/batch",
+        "summary": "the SERVER-side batched ingestion envelope every official server SDK sends: {batch:[<message>...], writeKey, sentAt}, each message discriminated by its own `type`",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "SDK WIRE LITERAL. @segment/analytics-node@2.3.0 src/plugins/segmentio/publisher.ts:73-76 builds the one and only URL this SDK ever posts to: tryCreateFormattedUrl(host ?? 'https://api.segment.io', path ?? '/v1/batch'); the body at :243-247 is JSON.stringify({batch: events, writeKey: this._writeKey, sentAt: new Date()}). It is the SOLE real path literal in var/line/segment/dossier/wire.json pathLiterals (the other, '/bar', is a JSDoc example). Corroborated in a second first-party SDK (analytics-python segment/analytics/request.py: url = remove_trailing_slash(host or 'https://api.segment.io') + '/v1/batch') and in the vendor's own reference, github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Batch'.",
+        "tier": "core"
+    },
+    {
+        "id": "browser_track",
+        "area": "track",
+        "method": "POST",
+        "path": "/v1/t",
+        "summary": "analytics.js's short-form tracking route on the api.segment.io/v1 base — the path a browser proxy must forward",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/website/javascript/custom-proxy.md:123-125 documents the Analytics.js `integrations['Segment.io'].apiHost` proxy as: '// POST https://MY-CUSTOM-API-PROXY.com/v1/t --> proxies to // https://api.segment.io/v1/t'. Only the `/v1/t` short form appears on a first-party page; the sibling short routes analytics.js may use for the other call types are NOT documented anywhere in segment-docs and are deliberately not invented here. No literal in @segment/analytics-node@2 (a server SDK; this is the browser route).",
+        "tier": "niche"
+    },
+    {
+        "id": "group",
+        "area": "group",
+        "method": "POST",
+        "path": "/v1/group",
+        "summary": "associate an identified user with a group (company/account/team) and record group traits",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Group' declares `POST https://api.segment.io/v1/group` with a worked body {userId, groupId, traits, timestamp, writeKey} and a field table naming groupId and group traits. Absent from @segment/analytics-node@2's wire surface (batched as type:'group').",
+        "tier": "core"
+    },
+    {
+        "id": "identify",
+        "area": "identify",
+        "method": "POST",
+        "path": "/v1/identify",
+        "summary": "tie a user to their actions and record `traits` about them",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Identify' declares `POST https://api.segment.io/v1/identify` with a worked body {userId, traits, context, timestamp, writeKey} and a field table (anonymousId, context, integrations, timestamp, identify traits, userId); the '## Selecting Destinations' section posts an integrations-bearing identify to the same URL. Absent from @segment/analytics-node@2's wire surface (that SDK sends type:'identify' messages inside /v1/batch).",
+        "tier": "core"
+    },
+    {
+        "id": "mobile_batch",
+        "area": "batch",
+        "method": "POST",
+        "path": "/v1/b",
+        "summary": "the MOBILE batch endpoint — a distinct route from /v1/batch, which the vendor reserves for server-side sending",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/mobile/apple/index.md:163 and src/connections/sources/catalog/libraries/mobile/react-native/index.md:781: 'you must forward the batched events to https://api.segment.io/v1/b. The https://api.segment.io/v1/batch endpoint is reserved for events arriving from server-side sending, and proxying to that endpoint for your mobile events may result in unexpected behavior.' Also react-native/index.md:91, the `proxy` option: 'a batch url to post to instead of https://api.segment.io/v1/b'. No literal in @segment/analytics-node@2 — this is the Swift/Kotlin/React-Native route, and no mobile SDK is pinned in this dossier.",
+        "tier": "common"
+    },
+    {
+        "id": "oauth_token",
+        "area": "oauth",
+        "method": "POST",
+        "path": "/token",
+        "summary": "OAuth 2.0 client-credentials token exchange on the regional authorization server: a signed RS256 JWT client assertion is traded for a short-lived access token",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "SDK WIRE LITERAL (interpolated, which is why wire.json's plain-string grep missed it). @segment/analytics-node@2.3.0 src/lib/token-manager.ts requestAccessToken(): `const accessTokenEndpoint = ${this.authServer}/token`, POSTed as application/x-www-form-urlencoded with grant_type=client_credentials & client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer & client_assertion=<signed JWT> & scope; authServer defaults to 'https://oauth2.segment.io' (same file's constructor) and the EU value 'https://oauth2.eu1.segmentapis.com' is documented on src/lib/types.ts OAuthSettings.authServer. Corroborated by github.com/segmentio/segment-docs src/connections/oauth.md '## Obtain the access token', which names both regional authorization servers and the same four form parameters.",
+        "tier": "niche"
+    },
+    {
+        "id": "page",
+        "area": "page",
+        "method": "POST",
+        "path": "/v1/page",
+        "summary": "record a web page view, with optional category, name and properties",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Page' declares `POST https://api.segment.io/v1/page` with a worked body {userId, name, timestamp, writeKey} and a field table (anonymousId, context, integrations, page name, page properties, timestamp, userId). Absent from @segment/analytics-node@2's wire surface (batched as type:'page').",
+        "tier": "core"
+    },
+    {
+        "id": "pixel_alias",
+        "area": "pixel",
+        "method": "GET",
+        "path": "/v1/pixel/alias",
+        "summary": "Tracking Pixel API: an alias call carried in the query string, answering 200 with a 1x1 transparent GIF",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+        "tier": "niche"
+    },
+    {
+        "id": "pixel_group",
+        "area": "pixel",
+        "method": "GET",
+        "path": "/v1/pixel/group",
+        "summary": "Tracking Pixel API: a group call carried in the query string, answering 200 with a 1x1 transparent GIF",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+        "tier": "niche"
+    },
+    {
+        "id": "pixel_identify",
+        "area": "pixel",
+        "method": "GET",
+        "path": "/v1/pixel/identify",
+        "summary": "Tracking Pixel API: an identify call carried in the query string, answering 200 with a 1x1 transparent GIF",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+        "tier": "niche"
+    },
+    {
+        "id": "pixel_page",
+        "area": "pixel",
+        "method": "GET",
+        "path": "/v1/pixel/page",
+        "summary": "Tracking Pixel API: a page call carried in the query string, answering 200 with a 1x1 transparent GIF",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+        "tier": "niche"
+    },
+    {
+        "id": "pixel_screen",
+        "area": "pixel",
+        "method": "GET",
+        "path": "/v1/pixel/screen",
+        "summary": "Tracking Pixel API: a screen call carried in the query string, answering 200 with a 1x1 transparent GIF",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md '#### Pixel Routes' enumerates exactly six routes as a literal block — /v1/pixel/identify, /v1/pixel/group, /v1/pixel/alias, /v1/pixel/page, /v1/pixel/screen, /v1/pixel/track — under the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, with 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs'. Not in any SDK.",
+        "tier": "niche"
+    },
+    {
+        "id": "pixel_track",
+        "area": "pixel",
+        "method": "GET",
+        "path": "/v1/pixel/track",
+        "summary": "Tracking Pixel API: a track call carried in the query string (base64 `?data=` or plain params), answering 200 with a 1x1 transparent GIF",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/pixel-tracking-api/index.md gives the signature `https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>`, lists /v1/pixel/track among its six '#### Pixel Routes', states 'Each endpoint *always* responds with a 200 <empty-gif>, even if an error occurs', and shows both the base64 img-tag form (:67) and the unencoded query-param form (:61). Corroborated at src/connections/sources/custom-domain.md:79 and src/guides/how-to-guides/cross-channel-tracking.md:77. Not in any SDK: this route exists for email/ad contexts where JavaScript and POST are impossible.",
+        "tier": "niche"
+    },
+    {
+        "id": "screen",
+        "area": "screen",
+        "method": "POST",
+        "path": "/v1/screen",
+        "summary": "record a mobile app screen view, with optional category, name and properties",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Screen' declares `POST https://api.segment.io/v1/screen` with a worked body {userId, name, timestamp, writeKey}. @segment/analytics-node@2 exposes a .screen() method (src/app/analytics-node.ts) and its SegmentEventType union includes 'screen' (src/app/types/segment-event.ts), but the message still travels inside /v1/batch — no per-type path literal ships.",
+        "tier": "common"
+    },
+    {
+        "id": "track",
+        "area": "track",
+        "method": "POST",
+        "path": "/v1/track",
+        "summary": "record an action a user performed: required `event` name plus optional `properties`",
+        "pathParams": [],
+        "requiredQuery": [],
+        "requiredBody": [],
+        "successStatus": 200,
+        "responseSkeleton": null,
+        "specFile": "SURFACE.json (sdk/docs-ratified, no vendor spec exists)",
+        "evidence": "DOCS ONLY, NOT VERIFIED OFFLINE. github.com/segmentio/segment-docs src/connections/sources/catalog/libraries/server/http-api/index.md '## Track' declares `POST https://api.segment.io/v1/track` with a worked JSON body {userId, event, properties, context, timestamp, writeKey}; the same page's '### writeKey authentication' and '#### OAuth' curl examples both post to that exact URL. NO path literal for it exists in @segment/analytics-node@2 — that SDK batches every call type onto /v1/batch — so this entry is grounded in the vendor's reference page, not in shipped SDK bytes.",
+        "tier": "core"
+    }
+];
+const compiled = OPS.map((op) => ({ op, re: new RegExp('^' + op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\{([^}]+)\}/g, '(?<$1>[^/]+)') + '$') }));
+/** Match one request against the ratified surface. PURE LOOKUP — dispatch belongs to the pack. */
+export function matchOp(req) {
+    const url = new URL(req.path, 'http://twin.local');
+    const match = compiled.find((c) => c.op.method === req.method.toUpperCase() && c.re.test(url.pathname));
+    if (!match)
+        return undefined;
+    return { op: match.op, params: { ...(match.re.exec(url.pathname)?.groups ?? {}) }, query: url.searchParams };
+}
+/** First required query/body field missing, or undefined (empty for sdk-ratified surfaces —
+ *  validation truth lives in the pack's semantics, grounded per op). */
+export function missingRequired(op, query, body) {
+    for (const q of op.requiredQuery)
+        if (!query.has(q))
+            return q;
+    for (const f of op.requiredBody)
+        if (!body || typeof body !== 'object' || body[f] === undefined)
+            return f;
+    return undefined;
+}
+/** SCAFFOLD default error body — the A2 station replaces this with the vendor's REAL envelope. */
+export const errorBody = (message, field) => ({ success: false, message, ...(field ? { field } : {}) });

package/dist/src/segment-twin.d.ts

@@ -0,0 +1,98 @@
+import { type OpHandler, type TwinResponse } from './segment-surface.gen.js';
+export type SegmentTwinRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    root?: string;
+    /** Captured, deliberately NOT enforced: the vendor says a content-type of 'application/json'
+     *  "must be set" but never states what it does when one is absent or wrong, so inventing a
+     *  refusal here would be surface Segment does not have. Filed as
+     *  segment.api.limits.content_type_required. */
+    contentType?: string;
+    /** The raw Authorization header, when the caller sent one (Basic or Bearer). */
+    authorization?: string;
+    /** The WORLD instant this request is served at. Defaults to the world clock (R9). */
+    occurredAt?: string;
+};
+type Row = Record<string, unknown> & {
+    type?: string;
+    id?: string;
+};
+/** Every accepted message, oldest-first by ingestion ordinal. One row per Segment `messageId`. */
+export declare function events(root?: string): Row[];
+/** Users as identify (and alias) have folded them: merged traits + the ids they answer to. */
+export declare function identities(root?: string): Row[];
+/** Groups as `group` calls have folded them: merged group traits. */
+export declare function groups(root?: string): Row[];
+/** Messages the vendor ACCEPTS (200) and then drops. Twin-local observability, not vendor surface. */
+export declare function dropped(root?: string): Row[];
+/** Segment's error body. The SHAPE is grounded — analytics-python reads `payload["code"]` and
+ *  `payload["message"]` off any non-200 (segment/analytics/request.py) — but the vendor
+ *  publishes no vocabulary of `code` VALUES. The single documented literal is
+ *  `no_user_anon_id` (http-api/index.md '## Errors'); every other code below is descriptive and
+ *  is NOT claimed to be the vendor's own string. The gap is filed as
+ *  segment.api.errors.code_vocabulary and no capability asserts a code the vendor never printed. */
+export declare const segmentError: (status: number, code: string, message: string) => TwinResponse;
+/** Documented drop reasons. Only `no_user_anon_id` is a vendor literal (see above). */
+export type DropReason = 'no_user_anon_id' | 'track_missing_event' | 'group_missing_group_id' | 'alias_missing_previous_id' | 'unknown_message_type' | 'event_exceeds_32kb' | 'batch_exceeds_2500_events';
+export declare const SEGMENT_MAX_REQUEST_BYTES: number;
+export declare const SEGMENT_MAX_BATCH_BYTES: number;
+export declare const SEGMENT_MAX_BATCH_EVENTS = 2500;
+export type ResolvedAuth = {
+    writeKey: string | null;
+    scheme: 'body' | 'basic' | 'oauth' | 'none';
+    bearer: string | null;
+};
+/** Resolve the write key from whichever of the three documented schemes the caller used.
+ *  The BODY wins when it carries a writeKey, because the docs' OAuth example keeps the writeKey
+ *  in the payload while the header carries a different credential entirely; Basic is consulted
+ *  only when the body has none, which is exactly the analytics-node v1 shape. */
+export declare function resolveWriteKey(authorization: string | undefined, body: unknown): ResolvedAuth;
+export type SegmentMessage = Record<string, unknown>;
+export type SegmentEnvelope = {
+    messages: SegmentMessage[];
+    /** Batch-level context/integrations, merged into each message (see MERGE below). */
+    context: Record<string, unknown> | undefined;
+    integrations: Record<string, unknown> | undefined;
+    writeKey: string | null;
+    scheme: ResolvedAuth['scheme'];
+    sentAt: string | null;
+    /** true when the payload arrived through /v1/batch (a list) rather than a direct route. */
+    batched: boolean;
+};
+/** The five message types this twin models, plus the one it ratifies and refuses BY NAME.
+ *  The union is the SDK's own: `type SegmentEventType = 'track' | 'page' | 'identify' | 'alias'
+ *  | 'screen'` (src/app/types/segment-event.ts) widened with 'group', which the SDK's
+ *  `Analytics.group()` produces through CoreEventFactory. */
+export declare const MODELED_TYPES: readonly ["track", "identify", "page", "group", "alias"];
+export type ModeledType = (typeof MODELED_TYPES)[number];
+/** Ratified in SURFACE.json, deliberately not modeled: it earns the loud gap by name. */
+export declare const UNMODELED_TYPES: readonly ["screen"];
+/** THE per-message dispatcher. Every route funnels through it, so `/v1/batch`, `/v1/track` and
+ *  their siblings can never disagree about what a message means.
+ *
+ *  Two refusal modes, and the difference is deliberate:
+ *   • a DOCUMENTED rejection (no identifier, Track without a name, an over-cap or oversize
+ *     batch member) is ACCEPTED-AND-DROPPED — 200, nothing folded into `event` — because that is
+ *     what Segment does: "Segment returns a 200 response for all API requests except errors
+ *     caused by large payloads and JSON errors", and its list of silently-rejected events names
+ *     exactly these cases;
+ *   • a message whose `type` this twin has RATIFIED but not MODELED (today: `screen`) fails
+ *     LOUDLY by name and the WHOLE payload is refused with nothing stored. That is a deliberate
+ *     deviation from the vendor's 200 (ruled:
+ *     denominator:200-for-nearly-everything-so-the-twin-gap-is-a-deliberate-deviation): a silent
+ *     200 storing nothing is indistinguishable from success, which is the one thing a twin may
+ *     never do. Validation of every message therefore precedes ANY fold. */
+export declare function ingest(env: SegmentEnvelope, endpoint: string, root: string | undefined, at: string): Promise<TwinResponse>;
+/** The ctx a segment SEMANTICS handler gets: the generated one plus the WORLD instant. The
+ *  generated surface is data + pure helpers and never carries a clock, so the instant is threaded
+ *  here — `receivedAt` and every minted messageId derive from it (R9). */
+type SegmentOpHandler = (ctx: Parameters<OpHandler>[0] & {
+    occurredAt: string;
+}) => ReturnType<OpHandler>;
+export declare const SEMANTICS: Record<string, SegmentOpHandler>;
+/** Decode a request body into the shared envelope. `/v1/batch` carries `{batch: [...]}`; a
+ *  direct route carries ONE message at the top level, with the writeKey alongside it. */
+export declare function decodeEnvelope(parsed: unknown, auth: ResolvedAuth, isBatchRoute: boolean): SegmentEnvelope | undefined;
+export declare function handleSegmentTwinRequest(req: SegmentTwinRequest): Promise<TwinResponse>;
+export {};