@seamward/collector 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,307 @@
+# Seamward Node collector
+
+The Seamward collector observes third-party HTTP API, webhook, queue, and
+scheduled-feed behaviour from a Node.js backend. It batches redacted evidence
+asynchronously and never sits on the application's critical request path.
+
+This `0.1.0-alpha` release line is for pilot evaluation with Node.js 22 or newer.
+TypeScript and server-side JavaScript are supported. PHP, Go, browser, and edge
+runtime collectors are not shipped yet.
+
+## 1. Create the Seamward connection
+
+In Seamward:
+
+1. Open the workspace and create an application environment under **Settings**.
+2. Generate its ingest token and copy it immediately. The token is shown once.
+3. Create or open an integration.
+4. Copy the public Connection key from the integration's **Collector setup** tab.
+
+The Connection key contains public routing identifiers and grants no access by
+itself. The ingest token is a write-only secret: keep it in the backend secret
+manager and never put it in browser code, Git, logs, screenshots, or support
+messages.
+
+## 2. Install the pilot release
+
+```bash
+pnpm add @seamward/collector
+```
+
+or `npm install @seamward/collector`. This is a prerelease; pin the version
+through your lockfile as with any dependency.
+
+## 3. Configure the backend
+
+```ini
+SEAMWARD_WEBHOOK_CONNECTION_KEY=sw_conn_v1.replace_webhook
+SEAMWARD_HTTP_API_CONNECTION_KEY=sw_conn_v1.replace_http_api
+SEAMWARD_QUEUE_PUBLISH_CONNECTION_KEY=sw_conn_v1.replace_queue_publish
+SEAMWARD_QUEUE_CONSUME_CONNECTION_KEY=sw_conn_v1.replace_queue_consume
+SEAMWARD_FEED_EXPORT_CONNECTION_KEY=sw_conn_v1.replace_feed_export
+SEAMWARD_INGEST_TOKEN=sw_ing_replace_me
+```
+
+`SEAMWARD_INGEST_URL` is optional and only needed for a self-hosted Seamward
+deployment. For example, use `https://seamward.example/ingest`. The collector
+otherwise uses `https://api.seamward.com/ingest`.
+
+Create one collector per Integration boundary. An Integration has one direction
+and one protocol. Processes that observe multiple boundaries create a collector
+for each Connection key and may share the application environment's ingest
+token:
+
+```ts
+import { createSeamwardCollector } from "@seamward/collector";
+
+const connected = (connectionKey: string) =>
+  createSeamwardCollector({
+    connectionKey,
+    ingestToken: process.env.SEAMWARD_INGEST_TOKEN!,
+    endpoint: process.env.SEAMWARD_INGEST_URL,
+    deployment: {
+      service: "candidate-api",
+      release: process.env.RELEASE_VERSION,
+      commitSha: process.env.GITHUB_SHA,
+    },
+  });
+
+export const webhookCollector = connected(
+  process.env.SEAMWARD_WEBHOOK_CONNECTION_KEY!,
+);
+export const httpApiCollector = connected(
+  process.env.SEAMWARD_HTTP_API_CONNECTION_KEY!,
+);
+export const queuePublisherCollector = connected(
+  process.env.SEAMWARD_QUEUE_PUBLISH_CONNECTION_KEY!,
+);
+export const queueConsumerCollector = connected(
+  process.env.SEAMWARD_QUEUE_CONSUME_CONNECTION_KEY!,
+);
+export const feedExportCollector = connected(
+  process.env.SEAMWARD_FEED_EXPORT_CONNECTION_KEY!,
+);
+```
+
+Release and commit metadata are optional. The collector also recognises
+`SEAMWARD_COMMIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`,
+`RAILWAY_GIT_COMMIT_SHA`, and `GITHUB_SHA`. Invalid values are ignored instead
+of breaking the host application.
+
+## 4. Observe an inbound webhook
+
+Wrap the existing business handler; do not send the inbound request headers to
+Seamward.
+
+```ts
+const handleCandidateWebhook = webhookCollector.observeWebhook(
+  {
+    routeTemplate: "/webhooks/candidates",
+  },
+  async (payload) => {
+    const candidate = await candidateService.accept(payload);
+
+    return {
+      statusCode: 202,
+      eventType: "candidate.create",
+      outcome: {
+        accepted: true,
+        businessObjectType: "candidate",
+        businessObjectId: candidate.id,
+      },
+      correlation: { sourceEventId: candidate.providerEventId },
+    };
+  },
+);
+
+fastify.post("/webhooks/candidates", async (request, reply) => {
+  const result = await handleCandidateWebhook(
+    request.body as Record<string, unknown>,
+  );
+  return reply.code(result.statusCode ?? 200).send();
+});
+```
+
+Use stable route templates such as `/webhooks/candidates`, never concrete IDs,
+query strings, email addresses, or other high-cardinality values.
+
+## 5. Observe an outbound API call
+
+```ts
+const providerFetch = httpApiCollector.observeFetch({
+  routeTemplate: "/v1/candidates",
+  eventType: "candidate.create",
+  payloadLocation: "response",
+});
+
+const response = await providerFetch("https://provider.example/v1/candidates", {
+  method: "POST",
+  headers: {
+    authorization: `Bearer ${process.env.PROVIDER_TOKEN}`,
+    "content-type": "application/json",
+  },
+  body: JSON.stringify(candidate),
+});
+```
+
+The collector never receives the request headers. By default, it clones the
+response and inspects JSON asynchronously, so consuming the original response
+is not delayed. Set `payloadLocation: "request"` to observe the JSON request
+shape instead. String bodies and cloned `Request` bodies are inspected safely.
+For another body type, pass a local-only `requestPayload`; its values remain in
+the process and only its redacted structural shape enters the envelope.
+
+## 6. Observe a queue boundary
+
+Use the broker-neutral wrappers around the publish and consume functions you
+already own. Seamward does not acknowledge, retry, or otherwise control the
+broker operation.
+
+```ts
+const publishCandidate = queuePublisherCollector.observeQueuePublish(
+  {
+    queueName: "candidate-events",
+    eventType: "candidate.published",
+  },
+  async (message) => {
+    await broker.publish("candidate-events", message);
+    return { disposition: "acknowledged" as const };
+  },
+);
+
+const consumeCandidate = queueConsumerCollector.observeQueueConsumer(
+  {
+    queueName: "candidate-events",
+    eventType: "candidate.received",
+  },
+  async (message) => {
+    await candidateService.accept(message);
+    return { disposition: "acknowledged" as const };
+  },
+);
+```
+
+Use a stable queue, topic, or subscription label. Never use a message ID.
+Broker-specific adapters are not shipped in this pilot.
+
+## 7. Observe a scheduled feed
+
+Wrap one scheduled import or export run. The wrapper records completion,
+rejection, duration, attempt, and correlation evidence without changing the
+job's return value or error behaviour.
+
+```ts
+const exportCandidates = feedExportCollector.observeScheduledFeed(
+  {
+    feedName: "nightly-candidate-export",
+    direction: "outbound",
+    eventType: "candidate.exported",
+  },
+  async (payload) => {
+    await provider.upload(payload);
+    return { disposition: "completed" as const };
+  },
+);
+```
+
+The v0.2 wire envelope retains `method`, `routeTemplate`, and `statusCode` for
+backward compatibility. Queue and feed wrappers project their native concepts
+into those fields, so application code does not supply synthetic HTTP values.
+
+## 8. Redaction and correlation
+
+Payload values and headers are never included in the observation envelope. The
+collector derives only the structural shape (`string`, `number`, object fields,
+and so on) and its fingerprint before the envelope leaves the process. Field
+names remain visible because they are required for contract-drift detection.
+
+The default policy identifies these common secret-bearing fields:
+
+```text
+password, access_token, refresh_token, authorization, cookie, set-cookie
+```
+
+Give an application-specific policy version so evidence can be traced to the
+configuration that produced it:
+
+```ts
+const seamward = createSeamwardCollector({
+  connectionKey: process.env.SEAMWARD_CONNECTION_KEY!,
+  ingestToken: process.env.SEAMWARD_INGEST_TOKEN!,
+  policy: {
+    version: "candidate-api-v1",
+    dropFields: [
+      "password",
+      "access_token",
+      "refresh_token",
+      "authorization",
+      "cookie",
+      "set-cookie",
+      "full_name",
+      "email",
+      "phone_number",
+    ],
+    hashFields: [],
+  },
+});
+```
+
+Do not place identifiers in `eventType`, `routeTemplate`, release labels, or
+service names. Put only identifiers needed for reconciliation into
+`correlation.sourceEventId`, `correlation.idempotencyKey`, or
+`outcome.businessObjectId`. The collector converts those values to keyed
+SHA-256 hashes locally; Seamward receives no original identifier.
+
+## 9. Shutdown and health
+
+Flush before a controlled process shutdown:
+
+```ts
+process.once("SIGTERM", async () => {
+  await Promise.all([
+    webhookCollector.stop(),
+    httpApiCollector.stop(),
+    queuePublisherCollector.stop(),
+    queueConsumerCollector.stop(),
+    feedExportCollector.stop(),
+  ]);
+  process.exit(0);
+});
+```
+
+`stop()` clears the timer and attempts one final flush. `flush()` and `stop()`
+never reject because Seamward telemetry must not break the host application.
+Inspect bounded operational counters without logging observations or tokens:
+
+```ts
+const { enqueued, shipped, dropped, failedBatches, queueLength, buildErrors } =
+  httpApiCollector.stats();
+```
+
+Defaults:
+
+- flush interval: 5 seconds;
+- batch size: 50 observations;
+- in-memory queue: 1,000 observations;
+- overflow policy: drop oldest and increment `dropped`;
+- failed request policy: retain the batch and retry on the next flush;
+- application errors: preserve the application's original error behaviour.
+
+## 10. Verify the connection
+
+1. Start the backend with the Connection key and ingest token configured.
+2. Exercise one synthetic HTTP request, webhook, queue message, or feed run.
+3. Wait for the five-second automatic flush, or call `await httpApiCollector.flush()` for the collector you exercised.
+4. Return to the integration in Seamward and select **Check for observation**.
+5. Confirm the first observation time and deployment metadata.
+
+If the integration remains unobserved:
+
+- confirm the collector is running in the backend rather than the browser;
+- copy the Connection key again from the integration you are testing;
+- confirm the ingest token belongs to that integration's application environment;
+- inspect the relevant collector's `stats()` result for `failedBatches`, `dropped`, or `buildErrors`;
+- verify the local API is reachable at the configured ingest URL;
+- generate a new ingest token if the original was not saved or may be exposed.
+
+Do not disable redaction or log request bodies to troubleshoot the connection.

package/dist/connect.d.ts

@@ -0,0 +1,49 @@
+import { type Json } from "@seamward/contracts";
+import { type Collector, type CollectorConfig, type FetchMeta, type ObservedFetch, type QueueMeta, type QueueResult, type RecordInput, type ScheduledFeedMeta, type ScheduledFeedResult, type WebhookMeta, type WebhookResult } from "./observe.js";
+import type { RedactionPolicy } from "./redact.js";
+export interface ConnectOptions extends Pick<CollectorConfig, "deployment" | "builderDeps" | "maxBatchSize" | "flushIntervalMs" | "maxQueueSize" | "fetchFn" | "nowSec"> {
+    /** Override for self-hosted and local Seamward ingestion. */
+    endpoint?: string;
+    policy?: Omit<RedactionPolicy, "hashKey">;
+}
+export type CreateSeamwardCollectorConfig = ConnectOptions & {
+    /** Write-only server credential. Store this in an environment variable. */
+    ingestToken: string;
+} & ({
+    /** Public key that binds one source and integration. Grants no access by itself. */
+    connectionKey: string;
+    sourceKey?: never;
+} | {
+    /** Legacy public application/environment identifier. */
+    sourceKey: string;
+    connectionKey?: never;
+});
+export type ConnectedRecordInput = Omit<RecordInput, "integrationId"> & {
+    integrationKey?: string;
+};
+export type ConnectedWebhookMeta = Omit<WebhookMeta, "integrationId"> & {
+    integrationKey?: string;
+};
+export type ConnectedFetchMeta = Omit<FetchMeta, "integrationId"> & {
+    integrationKey?: string;
+};
+export type ConnectedQueueMeta = Omit<QueueMeta, "integrationId"> & {
+    integrationKey?: string;
+};
+export type ConnectedScheduledFeedMeta = Omit<ScheduledFeedMeta, "integrationId"> & {
+    integrationKey?: string;
+};
+export interface ConnectedCollector extends Omit<Collector, "record" | "observeWebhook" | "observeFetch"> {
+    record(input: ConnectedRecordInput): void;
+    observeWebhook<R extends WebhookResult | void>(meta: ConnectedWebhookMeta, handler: (payload: Json) => R | Promise<R>): (payload: Json) => Promise<R>;
+    observeFetch(meta: ConnectedFetchMeta, fetchFn?: typeof fetch): ObservedFetch;
+    observeQueuePublish<R extends QueueResult | void>(meta: ConnectedQueueMeta, publisher: (message: Json) => R | Promise<R>): (message: Json) => Promise<R>;
+    observeQueueConsumer<R extends QueueResult | void>(meta: ConnectedQueueMeta, consumer: (message: Json) => R | Promise<R>): (message: Json) => Promise<R>;
+    observeScheduledFeed<R extends ScheduledFeedResult | void>(meta: ConnectedScheduledFeedMeta, handler: (payload: Json) => R | Promise<R>): (payload: Json) => Promise<R>;
+}
+/**
+ * Backend collector setup. The public Source key identifies the deployed
+ * application; Integration keys route its observations, and the write-only
+ * ingest token authenticates and signs every batch.
+ */
+export declare function createSeamwardCollector(config: CreateSeamwardCollectorConfig): ConnectedCollector;

package/dist/connect.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { parseIngestToken, parseConnectionKey, parseIntegrationKey, parseSourceKey, } from "@seamward/contracts";
+import { createCollector, } from "./observe.js";
+const defaultPolicy = {
+    version: "seamward-default-v1",
+    dropFields: [
+        "password",
+        "access_token",
+        "refresh_token",
+        "authorization",
+        "cookie",
+        "set-cookie",
+    ],
+    hashFields: [],
+};
+function defaultIngestEndpoint() {
+    return process.env.SEAMWARD_INGEST_URL ?? "https://api.seamward.com/ingest";
+}
+/**
+ * Backend collector setup. The public Source key identifies the deployed
+ * application; Integration keys route its observations, and the write-only
+ * ingest token authenticates and signs every batch.
+ */
+export function createSeamwardCollector(config) {
+    const { connectionKey: rawConnectionKey, ingestToken: rawIngestToken, endpoint = defaultIngestEndpoint(), policy = defaultPolicy, sourceKey: rawSourceKey, ...options } = config;
+    let sourceKey;
+    let boundIntegrationKey = null;
+    let ingestToken;
+    try {
+        if (rawConnectionKey) {
+            const parsed = parseConnectionKey(rawConnectionKey);
+            sourceKey = parsed.sourceKey;
+            boundIntegrationKey = parsed.integrationKey;
+        }
+        else {
+            sourceKey = parseSourceKey(rawSourceKey ?? "");
+        }
+    }
+    catch {
+        throw new Error("Seamward connection key or source key is invalid");
+    }
+    try {
+        ingestToken = parseIngestToken(rawIngestToken);
+    }
+    catch {
+        throw new Error("Seamward ingest token is invalid");
+    }
+    const collector = createCollector({
+        endpoint,
+        sourceKey,
+        ingestToken,
+        // These placeholders satisfy the local strict envelope contract. The API
+        // replaces them with the token-bound scope before validation/persistence.
+        tenantId: "ten_authenticated",
+        environmentId: "env_authenticated",
+        policy: {
+            ...policy,
+            hashKey: createHash("sha256").update(ingestToken).digest("base64url"),
+        },
+        ...options,
+    });
+    function integrationId(value) {
+        const selected = value ?? boundIntegrationKey;
+        if (!selected) {
+            throw new Error("Seamward integration key is required when using a legacy source key");
+        }
+        return parseIntegrationKey(selected);
+    }
+    return {
+        record: ({ integrationKey, ...input }) => collector.record({
+            ...input,
+            integrationId: integrationId(integrationKey),
+        }),
+        observeWebhook: ({ integrationKey, ...meta }, handler) => collector.observeWebhook({ ...meta, integrationId: integrationId(integrationKey) }, handler),
+        observeFetch: ({ integrationKey, ...meta }, fetchFn) => collector.observeFetch({ ...meta, integrationId: integrationId(integrationKey) }, fetchFn),
+        observeQueuePublish: ({ integrationKey, ...meta }, publisher) => collector.observeQueuePublish({ ...meta, integrationId: integrationId(integrationKey) }, publisher),
+        observeQueueConsumer: ({ integrationKey, ...meta }, consumer) => collector.observeQueueConsumer({ ...meta, integrationId: integrationId(integrationKey) }, consumer),
+        observeScheduledFeed: ({ integrationKey, ...meta }, handler) => collector.observeScheduledFeed({ ...meta, integrationId: integrationId(integrationKey) }, handler),
+        flush: () => collector.flush(),
+        stop: () => collector.stop(),
+        stats: () => collector.stats(),
+    };
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}

package/dist/deployment-context.d.ts

@@ -0,0 +1,8 @@
+import { type DeploymentContext } from "@seamward/contracts";
+export type DeploymentEnvironment = Readonly<Record<string, string | undefined>>;
+/**
+ * Resolve bounded, low-cardinality deployment evidence without making it a
+ * collector requirement. Explicit SDK values win; known runtime variables are
+ * fallbacks. Invalid values are ignored rather than breaking host telemetry.
+ */
+export declare function resolveDeploymentContext(explicit?: Partial<DeploymentContext>, environment?: DeploymentEnvironment): DeploymentContext | undefined;

package/dist/deployment-context.js

@@ -0,0 +1,43 @@
+import { deploymentContextSchema, } from "@seamward/contracts";
+const commitEnvironmentKeys = [
+    "SEAMWARD_COMMIT_SHA",
+    "VERCEL_GIT_COMMIT_SHA",
+    "RENDER_GIT_COMMIT",
+    "RAILWAY_GIT_COMMIT_SHA",
+    "GITHUB_SHA",
+];
+function validField(key, candidates) {
+    for (const candidate of candidates) {
+        if (candidate === undefined || candidate.length === 0)
+            continue;
+        const parsed = deploymentContextSchema.safeParse({ [key]: candidate });
+        if (parsed.success)
+            return parsed.data[key];
+    }
+    return undefined;
+}
+/**
+ * Resolve bounded, low-cardinality deployment evidence without making it a
+ * collector requirement. Explicit SDK values win; known runtime variables are
+ * fallbacks. Invalid values are ignored rather than breaking host telemetry.
+ */
+export function resolveDeploymentContext(explicit = {}, environment = process.env) {
+    const service = validField("service", [explicit.service, environment.SEAMWARD_SERVICE]);
+    const commitSha = validField("commitSha", [
+        explicit.commitSha?.toLowerCase(),
+        ...commitEnvironmentKeys.map((key) => environment[key]?.toLowerCase()),
+    ]);
+    const release = validField("release", [
+        explicit.release,
+        environment.SEAMWARD_RELEASE,
+        commitSha?.slice(0, 12),
+    ]);
+    const context = {
+        ...(service ? { service } : {}),
+        ...(release ? { release } : {}),
+        ...(commitSha ? { commitSha } : {}),
+    };
+    const parsed = deploymentContextSchema.safeParse(context);
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=deployment-context.js.map

package/dist/deployment-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-context.js","sourceRoot":"","sources":["../src/deployment-context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAI7B,MAAM,qBAAqB,GAAG;IAC5B,qBAAqB;IACrB,uBAAuB;IACvB,mBAAmB;IACnB,wBAAwB;IACxB,YAAY;CACJ,CAAC;AAEX,SAAS,UAAU,CACjB,GAAM,EACN,UAAqC;IAErC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChE,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QACvE,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,WAAuC,EAAE,EACzC,cAAqC,OAAO,CAAC,GAAG;IAEhD,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACxF,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,EAAE;QACxC,QAAQ,CAAC,SAAS,EAAE,WAAW,EAAE;QACjC,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC;KACvE,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,EAAE;QACpC,QAAQ,CAAC,OAAO;QAChB,WAAW,CAAC,gBAAgB;QAC5B,SAAS,EAAE,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;KACxB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG;QACd,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC;IACF,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC"}

package/dist/envelope-builder.d.ts

@@ -0,0 +1,51 @@
+import { type DeploymentContext, type Json, type ObservationEnvelope } from "@seamward/contracts";
+import { type RedactionPolicy } from "./redact.js";
+/**
+ * Builds a valid ObservationEnvelope from one observed request/response.
+ *
+ * Privacy order of operations (the load-bearing design):
+ * 1. The structural fingerprint is computed from the RAW payload - signatures
+ *    are shape-only (field names + types, never values), so this is safe and
+ *    keeps drift detection faithful to what the provider actually sent, even
+ *    for fields the policy would drop from any stored content.
+ * 2. Correlation identifiers leave the process only as keyed hashes.
+ * 3. The envelope schema is strict and has NO field for headers or bodies:
+ *    a leak would require changing @seamward/contracts, not a builder bug.
+ *
+ * Pure: clock and id generation are injected for determinism. The built
+ * envelope is validated through the strict schema before it is returned.
+ */
+export interface ObservationInput {
+    tenantId: string;
+    environmentId: string;
+    integrationId: string;
+    direction: "inbound" | "outbound";
+    protocol: "http-webhook" | "http-api" | "scheduled-feed" | "queue";
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    routeTemplate: string;
+    payloadLocation?: "request" | "response" | "message";
+    statusCode: number;
+    durationMs: number;
+    attempt?: number;
+    /** Low-cardinality provider event label; never put identifiers or PII here. */
+    eventType?: string;
+    /** Raw payload - used for shape-only fingerprinting; never shipped. */
+    payload?: Json;
+    declaredContractVersion?: string;
+    deployment?: DeploymentContext;
+    correlation?: {
+        traceId?: string;
+        sourceEventId?: string;
+        idempotencyKey?: string;
+    };
+    outcome?: {
+        accepted: boolean;
+        businessObjectType?: string;
+        businessObjectId?: string;
+    };
+}
+export interface BuilderDeps {
+    now?: () => Date;
+    newId?: () => string;
+}
+export declare function buildEnvelope(input: ObservationInput, policy: RedactionPolicy, deps?: BuilderDeps): ObservationEnvelope;

package/dist/envelope-builder.js

@@ -0,0 +1,72 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { ENVELOPE_VERSION, OPERATION_IDENTITY_VERSION, defaultPayloadLocation, parseEnvelope, schemaFingerprint, shapeOf, } from "@seamward/contracts";
+import { keyedHash } from "./redact.js";
+export function buildEnvelope(input, policy, deps = {}) {
+    const now = deps.now ?? (() => new Date());
+    const newId = deps.newId ?? (() => randomUUID().replaceAll("-", ""));
+    const fingerprint = schemaFingerprint(input.payload ?? null);
+    const correlation = {};
+    if (input.correlation?.traceId)
+        correlation.traceId = input.correlation.traceId;
+    if (input.correlation?.sourceEventId) {
+        correlation.sourceEventIdHash = keyedHash(input.correlation.sourceEventId, policy.hashKey);
+    }
+    if (input.correlation?.idempotencyKey) {
+        correlation.idempotencyKeyHash = keyedHash(input.correlation.idempotencyKey, policy.hashKey);
+    }
+    correlation.hashNamespace =
+        policy.hashNamespace ??
+            `key:${createHmac("sha256", policy.hashKey)
+                .update("seamward-hash-namespace-v1", "utf8")
+                .digest("hex")
+                .slice(0, 32)}`;
+    const outcome = input.outcome
+        ? {
+            accepted: input.outcome.accepted,
+            ...(input.outcome.businessObjectType
+                ? { businessObjectType: input.outcome.businessObjectType }
+                : {}),
+            ...(input.outcome.businessObjectId
+                ? {
+                    businessObjectIdHash: keyedHash(input.outcome.businessObjectId, policy.hashKey),
+                }
+                : {}),
+        }
+        : { accepted: input.statusCode !== 0 && input.statusCode < 400 };
+    return parseEnvelope({
+        envelopeVersion: ENVELOPE_VERSION,
+        eventId: `evt_${newId()}`,
+        tenantId: input.tenantId,
+        environmentId: input.environmentId,
+        integrationId: input.integrationId,
+        direction: input.direction,
+        protocol: input.protocol,
+        occurredAt: now().toISOString(),
+        operationIdentityVersion: OPERATION_IDENTITY_VERSION,
+        ...(input.deployment ? { deployment: input.deployment } : {}),
+        ...(input.eventType ? { eventType: input.eventType } : {}),
+        correlation,
+        contract: {
+            ...(input.declaredContractVersion
+                ? { declaredVersion: input.declaredContractVersion }
+                : {}),
+            observedFingerprint: fingerprint,
+        },
+        transport: {
+            method: input.method,
+            routeTemplate: input.routeTemplate,
+            payloadLocation: input.payloadLocation ?? defaultPayloadLocation(input),
+            statusCode: input.statusCode,
+            durationMs: input.durationMs,
+            attempt: input.attempt ?? 1,
+        },
+        payload: {
+            storage: "none",
+            schemaFingerprint: fingerprint,
+            schemaShape: shapeOf(input.payload ?? null),
+            redactionPolicyVersion: policy.version,
+        },
+        outcome,
+    });
+}
+//# sourceMappingURL=envelope-builder.js.map

package/dist/envelope-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-builder.js","sourceRoot":"","sources":["../src/envelope-builder.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { redactPayload, redactHeaders, keyedHash, ALWAYS_DROPPED_HEADERS, } from "./redact.js";
+export type { RedactionPolicy } from "./redact.js";
+export { buildEnvelope } from "./envelope-builder.js";
+export type { ObservationInput, BuilderDeps } from "./envelope-builder.js";
+export { createShipper } from "./shipper.js";
+export type { Shipper, ShipperConfig, ShipperStats } from "./shipper.js";
+export { createCollector } from "./observe.js";
+export type { Collector, CollectorConfig, CollectorStats, FetchMeta, ObservedFetch, QueueMeta, QueueResult, RecordInput, ScheduledFeedMeta, ScheduledFeedResult, WebhookMeta, WebhookResult, } from "./observe.js";
+export { resolveDeploymentContext } from "./deployment-context.js";
+export type { DeploymentEnvironment } from "./deployment-context.js";
+export { createSeamwardCollector } from "./connect.js";
+export type { CreateSeamwardCollectorConfig, ConnectedCollector, ConnectedFetchMeta, ConnectedQueueMeta, ConnectedRecordInput, ConnectedScheduledFeedMeta, ConnectedWebhookMeta, ConnectOptions, } from "./connect.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { redactPayload, redactHeaders, keyedHash, ALWAYS_DROPPED_HEADERS, } from "./redact.js";
+export { buildEnvelope } from "./envelope-builder.js";
+export { createShipper } from "./shipper.js";
+export { createCollector } from "./observe.js";
+export { resolveDeploymentContext } from "./deployment-context.js";
+export { createSeamwardCollector } from "./connect.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAgB/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}