@volter/twin-segment

Legacy connector helpers: this package still has callable helpers using the retired v1 syncPull API. Those paths require migration before use on the current kernel; older helper descriptions below do not establish current compatibility. Check the generated index for protocol standing and use the shared model for current state semantics.

A local, stateful replica of Segment's HTTP Tracking API. Point an unmodified @segment/analytics-node client at it with nothing but the SDK's own host setting and your events fold into durable twin state — offline, deterministic, with no write key that means anything and no traffic leaving the machine.

bunx world-segment serve --port 8787     # then: new Analytics({ writeKey, host: 'http://localhost:8787' })
bunx world-segment ops                   # the ratified surface, one line per operation
bunx world-segment conformance           # vendor-property checks over the modeled plane

Coverage

The denominator is AUTHORED, not compiled. Segment publishes no machine-readable spec for its ingestion surface, so this pack's sixteen operations were ratified one at a time from evidence at var/line/segment/SURFACE.json, each entry carrying the source it stands on:

| tier | ops | grounding | |---|---|---| | SDK wire literal | 2 | POST /v1/batch (the single URL @segment/[email protected]'s Publisher ever posts to) and POST /token on the OAuth authorization server | | Docs only, not verified offline | 14 | the six direct POST /v1/{track,identify,page,screen,group,alias} routes, the mobile batch route POST /v1/b, analytics.js's POST /v1/t, and the six literal Pixel Routes GET /v1/pixel/{...} |

Docs grounding comes from github.com/segmentio/segment-docs, the vendor's own documentation source repository — segment.com answers 403 to non-browser clients, so the rendered pages were not read. Rulings and the ratified vendor facts live in var/line/segment/RULINGS.json and FACTS.json.

Coverage reads honestly partial: the ingestion half of the tracking plane is modeled, and everything else is a filed todo. That is the intended shape — a broad honest denominator beats a thin self-portrait.

What is modeled

• POST /v1/batch — the envelope every official server SDK sends, {batch, writeKey, sentAt}, dispatched per message by each message's own type. Batch-level context and integrations merge into every message, message-level keys winning, as the vendor documents.
• The direct routes POST /v1/{track,identify,page,group,alias}, which fold through the same code path as their batched equivalents, so the two can never disagree.
• All three documented auth schemes: writeKey in the body with no header (the SDK's own default), HTTP Basic with the write key as the username and an empty password (analytics-node v1's shape), and OAuth Bearer alongside a payload write key.
• The vendor's accept-and-drop semantics. Segment "returns a 200 response for all API requests except errors caused by large payloads and JSON errors", and then silently rejects events with no userId/anonymousId (its own no_user_anon_id error), Tracks with no event name, and batch members past 2,500 events or 32KB. The twin reproduces that exactly and records each drop in a local dropped projection so the outcome stays inspectable.
• messageId dedupe, the vendor's own idempotency key — across requests and within one batch.
• The documented 400s (invalid JSON, oversize payload) with the {code, message} envelope analytics-python parses off every non-200.

Deliberate deviation: unmodeled operations fail LOUDLY

The real vendor answers 200 to almost everything. This twin answers a 404 [twin gap] naming the operation for anything it has ratified but not modeled — /v1/b, /v1/t, /v1/screen, the six pixel routes, /token, and the screen message type inside an otherwise-modeled batch. That is a knowing departure from fidelity, and the right one: a 200 that stores nothing is indistinguishable from success, which is the one thing a twin may never do. It is ruled in var/line/segment/RULINGS.json and pinned by segment.api.fail_loudly.

What this denominator excludes, and why

Each of these is a ruling, not an omission:

• The Public API (api.segmentapis.com) — workspaces, sources, destinations, warehouses, tracking plans. A different product on a different host behind a workspace token. Its host is not claimed in the injector map, so a Public API call from a world still reaches the real vendor: a named exposure, and the first thing a follow-up article should close.
• The Profile API (profiles.segment.com) — a different host, credential and product tier, returning resolved profiles rather than ingested events.
• cdn.segment.com/v1/projects/{writeKey}/settings — real and first-party, but that host also serves the analytics.js bundle, so intercepting it would break loading the real library.
• Inbound webhooks — this vendor has none on the tracking plane. Segment's "Webhooks (Actions)" is a destination (Segment → you).
• The Objects APIs (objects.segment.com/v1/set and the four /v0 routes of objects-bulk-api.segmentapis.com) — real, first-party, on the same server-source catalog branch and behind the same source write key, but beta, warehouse-object loading rather than event ingestion, and unreachable by any analytics-<language> client, so this article's SDK-anchored method has nothing to verify against. Neither host is claimed in the injector map — the same named exposure the Public API carries, and the same follow-up (denominator:object-apis-plane-named-but-not-claimed, filed by A3).

Connector

Push replays locally-ingested flushes onto the real POST /v1/batch through an injected client, rebuilding the SDK's own envelope. Pull mirrors nothing, and that is a vendor fact: every one of the sixteen ratified operations is a write. Segment's own answer to "did my event land" is the browser Source Debugger, a live websocket view — not an API. Rather than fake an empty account over real observed state, the gap is filed as segment.connector.pull.

UI mirror — the Source Debugger

Segment is owed a mirror. Its core browser job — wiring sources to destinations, watching the Source Debugger, editing tracking plans — is exactly the "the UI is the product" case, so ui-scope.json rules needsUi: true.

The Source Debugger is built (segment.ui.debugger): a React screen showing the two live streams a source has, the accepted messages with their type, label, subject and properties, and the dropped ones with the REASON they were refused. It cannot BE an API capability: all sixteen ratified operations are ingests and none of them reads a message back, so the vendor's own answer to "my event returned 200 and never arrived" is a screen rather than a call.

The dropped pane is the twin's, not the vendor's — a deliberate superset, labelled as one on the screen itself. Segment's real Source Debugger shows what a source RECEIVED; it has no accepted-then-silently-dropped view, because the vendor answers 200 and discards. This twin records the refusal instead, which is the only way that failure becomes observable at all. Of the seven drop reasons it shows, only no_user_anon_id is a string Segment itself prints (its Errors page); the other six are this pack's own descriptive labels and the row marks each of them twin label.

bun run packages/twin/segment/src/cli.ts mirror --port 4100   # the debugger + the tracking API, one origin

The screen reads the twin's own store door (GET /twin/store/events, …/dropped) on the same origin the tracking routes are served on — one serving code path, so the screen and its data cannot drift. A real headless-Chromium journey (segment-journey.uitest.ts, segment.journey.debugger) drives it end to end.

Two screens remain filed as live todos rather than fabricated: segment.ui.connections (the Connections graph, which needs the Public API plane this pack does not twin) and segment.ui.profiles (a user/group explorer over the identity projections). Cite those two as a tracked gap, never as precedent for omitting a mirror.

The store doors

The HTTP Tracking API is write-only: every route is an ingest and none of them reads a message back. What was accepted — and what was accepted-and-dropped, which Segment answers 200 to and never reports — is read through the twin's own named projections, GET /twin/store/{events, identities,groups,dropped}: the read-only doors the programming model gives a twin whose vendor has no listing endpoint (the mailgun precedent). They are deliberately out of the capability manifest: counting scaffolding the vendor does not have would pad the denominator. GET /twin names them under stores.

Rate budget

The vendor publishes 1,000 requests per second per workspace, and this pack deliberately does not adopt it: that is a workspace-wide production-throughput recommendation, not a per-connector allowance, and this pack's only live caller is a replay path. The declaration sits at exactly the kernel fallback's shape (60 weighted units / 60s at defaultWeight 2). See src/segment-budget.ts for the full reasoning, the figures, their source and the access date.

Fidelity test

src/segment-sdk.integration.test.ts drives the real, unmodified @segment/analytics-node (pinned ^2.3.0) against an in-process twin server, configured only through the SDK's own public host/flushAt/maxRetries settings — configuration, not modification. It asserts the SDK's own delivery verdict, so a twin answering the wrong status cannot pass.