@sempdev/semp 0.4.3

package/dist/delivery/stage_partition.js

@@ -0,0 +1,122 @@
+/**
+ * Staged-delivery partition computation per DELIVERY.md §3.2.1.
+ *
+ * Given a user's device directory, the per-device scoped
+ * certificates, the set of device public keys for which an inbound
+ * envelope's seal carries an enclosure-recipient wrap, and the
+ * sender address, returns the slice of {@link StagedHeldStage}
+ * values the staging runner feeds into the held-envelope queue.
+ *
+ * @module
+ */
+import { scopeAllowsSender } from "../keys/device_certificate.js";
+/**
+ * Compute the §3.2.1 stage partition for an inbound envelope.
+ *
+ * Algorithm:
+ *
+ *  1. Walk the directory; for each device whose pubkey is in
+ *     `enclosureRecipients`:
+ *     - Full-access devices are deferred (their stage is computed
+ *       implicitly per §10.3.3.1: `max(delegated_stages) + 1`).
+ *     - Delegated devices are evaluated against their scoped cert:
+ *       fetch the cert, run `scope.receive` against `senderAddress`.
+ *       Devices whose receive matcher rejects the envelope (mode,
+ *       allow/deny, or rate limit at the matcher level) are
+ *       excluded from the partition entirely.
+ *  2. Compute the implicit full-access stage as
+ *     `max(delegated_stages_with_mode_not_none) + 1`, taken across
+ *     ALL delegates with `receive.mode !== "none"` — not just those
+ *     that allowed THIS envelope. Matches §10.3.3.1's "the maximum
+ *     is taken over all delegated devices of the account that have
+ *     a receive matcher whose mode is not none". When no such
+ *     delegate exists, full-access devices are at stage 1 and
+ *     staging is a no-op.
+ *  3. Group eligible devices by stage and emit a sorted, monotonic
+ *     `StagedHeldStage[]`. Stages with no devices are pruned.
+ *
+ * Does NOT consult §10.3.3.3 rate-limit counters; rate-limit gating
+ * is the caller's concern. The matcher mode and allow/deny ARE
+ * checked.
+ *
+ * Returns an empty array when no eligible devices remain (the
+ * envelope is undeliverable to any device of the account; the
+ * caller surfaces this as silent or rejected per its own policy).
+ */
+export function partitionStages(input) {
+    const eligible = [];
+    const fullAccessIds = [];
+    let maxDelegateMode = 0;
+    for (const dev of input.directory.devices) {
+        const recipientWanted = input.enclosureRecipients.has(dev.device_public_key);
+        if (dev.role === "full_access") {
+            if (recipientWanted) {
+                fullAccessIds.push(dev.device_id);
+            }
+            continue;
+        }
+        // Delegated device.
+        const cert = input.certificateProvider(dev.device_id);
+        if (cert === null) {
+            // No current cert: per §10.3.7.3 step 3, stop delivering.
+            continue;
+        }
+        // max-stage tally first: every delegate whose mode is not "none"
+        // contributes to the implicit full-access stage, even if its
+        // allow/deny rejects THIS envelope.
+        if (cert.scope.receive.mode !== "none") {
+            const stage = cert.scope.receive.delivery_stage ?? 0;
+            if (stage > maxDelegateMode) {
+                maxDelegateMode = stage;
+            }
+        }
+        if (!recipientWanted) {
+            continue;
+        }
+        if (cert.scope.receive.mode === "none") {
+            continue;
+        }
+        if (!scopeAllowsSender(cert.scope.receive, input.senderAddress)) {
+            // Sender does not pass the matcher; exclude per §3.2.1.
+            continue;
+        }
+        let stage = cert.scope.receive.delivery_stage ?? 0;
+        if (stage < 1) {
+            // Defensive: a delegated cert without a stage gets stage 1 so
+            // it does not collide with the full-access implicit stage.
+            stage = 1;
+        }
+        eligible.push({ deviceId: dev.device_id, stage });
+    }
+    // Implicit full-access stage per §10.3.3.1 / §3.2.1.
+    const fullAccessStage = maxDelegateMode > 0 ? maxDelegateMode + 1 : 1;
+    for (const id of fullAccessIds) {
+        eligible.push({ deviceId: id, stage: fullAccessStage });
+    }
+    if (eligible.length === 0) {
+        return [];
+    }
+    // Group by stage, then emit a sorted slice.
+    const byStage = new Map();
+    for (const e of eligible) {
+        const list = byStage.get(e.stage);
+        if (list === undefined) {
+            byStage.set(e.stage, [e.deviceId]);
+        }
+        else {
+            list.push(e.deviceId);
+        }
+    }
+    const stages = Array.from(byStage.keys()).sort((a, b) => a - b);
+    const out = [];
+    for (const s of stages) {
+        const ids = byStage.get(s).slice().sort();
+        out.push({
+            stage: s,
+            pending_device_ids: ids,
+            dispositions: [],
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=stage_partition.js.map

package/dist/delivery/stage_partition.js.map

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

package/dist/delivery/staged_runner.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Staged-delivery runtime per DELIVERY.md §3.2.
+ *
+ * Drives the wait-and-aggregate loop:
+ *
+ *   - {@link StagedRunner.hold} registers a held envelope with its
+ *     stage partition (output of
+ *     {@link "./stage_partition".partitionStages}) and immediately
+ *     delivers to the lowest stage.
+ *   - {@link StagedRunner.ingestDisposition} records a stage-N
+ *     device's decision per §3.2.5.
+ *   - {@link StagedRunner.tick} advances envelopes whose current
+ *     stage has completed (every pending device emitted, or the
+ *     stage timeout elapsed per §3.2.4).
+ *
+ * Single-process, callable across many envelopes. JS event-loop
+ * concurrency: each call is run-to-completion atomic. There is no
+ * cross-thread state.
+ *
+ * @module
+ */
+import { type Disposition, type StagedHeldStage } from "./disposition.js";
+/** Hook delivering an envelope to one stage's pending device set. */
+export type StageDeliverFunc = (envelopeId: string, stage: number, deviceIds: string[]) => Promise<void>;
+/** Hook invoked when aggregation at any stage produces `suppress`. */
+export type StageSuppressFunc = (envelopeId: string, stage: number) => Promise<void>;
+/** Hook invoked when every stage advances without suppress. */
+export type StageCompleteFunc = (envelopeId: string) => Promise<void>;
+/** Inputs to {@link StagedRunner}. */
+export interface StagedRunnerConfig {
+    deliver: StageDeliverFunc;
+    suppress: StageSuppressFunc;
+    complete: StageCompleteFunc;
+    /** Per-stage wait window. Defaults to {@link DefaultStageTimeoutMs}. */
+    stageTimeoutMs?: number;
+    /** Wall-clock hook; defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+/** Sentinel error: envelope is already in the held queue. */
+export declare class EnvelopeAlreadyHeldError extends Error {
+    readonly name = "EnvelopeAlreadyHeldError";
+    constructor(envelopeId: string);
+}
+/** Sentinel error: envelope is not in the held queue. */
+export declare class EnvelopeNotHeldError extends Error {
+    readonly name = "EnvelopeNotHeldError";
+    constructor(envelopeId: string);
+}
+/**
+ * Staged-delivery runtime. Concurrency-safe within a single JS event
+ * loop (run-to-completion).
+ */
+export declare class StagedRunner {
+    private readonly cfg;
+    private readonly heldMap;
+    constructor(cfg: StagedRunnerConfig);
+    /**
+     * Register `envelopeId` with `stages` and deliver to the lowest
+     * stage. `stages[i].stage` MUST be monotonically increasing.
+     * Stages with empty `pending_device_ids` are pruned.
+     */
+    hold(envelopeId: string, stages: StagedHeldStage[]): Promise<void>;
+    /**
+     * Record `d` for `envelopeId`'s current stage per §3.2.5.
+     *
+     * `submitterDeviceId` is the device_id bound to the session that
+     * delivered the disposition; it MUST equal `d.device_id`.
+     *
+     * Idempotent on repeats from the same device — keeps the FIRST
+     * disposition (conservative aggregation).
+     */
+    ingestDisposition(envelopeId: string, submitterDeviceId: string, d: Disposition): void;
+    /**
+     * Advance every held envelope whose current stage is complete.
+     * Returns the number of envelopes advanced and the first
+     * non-fatal callback error encountered (per-envelope errors do
+     * not abort the tick).
+     */
+    tick(): Promise<{
+        advanced: number;
+        firstError?: Error;
+    }>;
+    /**
+     * Recompute a held envelope's stage partition per §3.2.6 in
+     * response to a delegated device's certificate being updated or
+     * revoked while the envelope is in flight. `newStages` is the
+     * freshly-computed partition (typically the output of
+     * `partitionStages` over the current directory + cert state).
+     *
+     * Carries forward dispositions already collected at the current
+     * stage. Stages strictly below the current stage have already
+     * been processed and are not part of the held entry.
+     */
+    reevaluate(envelopeId: string, newStages: StagedHeldStage[]): void;
+    /** Whether `envelopeId` is currently held. */
+    isHeld(envelopeId: string): boolean;
+    /** Number of envelopes currently held. */
+    size(): number;
+}
+//# sourceMappingURL=staged_runner.d.ts.map

package/dist/delivery/staged_runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged_runner.d.ts","sourceRoot":"","sources":["../../src/delivery/staged_runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,eAAe,EAKrB,MAAM,kBAAkB,CAAC;AAE1B,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,CAC7B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EAAE,KAChB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG,CAC9B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEtE,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,6DAA6D;AAC7D,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAkB,IAAI,8BAA8B;gBACxC,UAAU,EAAE,MAAM;CAG/B;AAED,yDAAyD;AACzD,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;gBACpC,UAAU,EAAE,MAAM;CAG/B;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAE4B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;gBAE7C,GAAG,EAAE,kBAAkB;IAsBnC;;;;OAIG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDxE;;;;;;;;OAQG;IACH,iBAAiB,CACf,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,EACzB,CAAC,EAAE,WAAW,GACb,IAAI;IAsCP;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,KAAK,CAAA;KAAE,CAAC;IAkF/D;;;;;;;;;;OAUG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,IAAI;IAsClE,8CAA8C;IAC9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC,0CAA0C;IAC1C,IAAI,IAAI,MAAM;CAGf"}

package/dist/delivery/staged_runner.js

@@ -0,0 +1,277 @@
+/**
+ * Staged-delivery runtime per DELIVERY.md §3.2.
+ *
+ * Drives the wait-and-aggregate loop:
+ *
+ *   - {@link StagedRunner.hold} registers a held envelope with its
+ *     stage partition (output of
+ *     {@link "./stage_partition".partitionStages}) and immediately
+ *     delivers to the lowest stage.
+ *   - {@link StagedRunner.ingestDisposition} records a stage-N
+ *     device's decision per §3.2.5.
+ *   - {@link StagedRunner.tick} advances envelopes whose current
+ *     stage has completed (every pending device emitted, or the
+ *     stage timeout elapsed per §3.2.4).
+ *
+ * Single-process, callable across many envelopes. JS event-loop
+ * concurrency: each call is run-to-completion atomic. There is no
+ * cross-thread state.
+ *
+ * @module
+ */
+import { DefaultStageTimeoutMs, aggregateDispositions, isStageComplete, validateDisposition, } from "./disposition.js";
+/** Sentinel error: envelope is already in the held queue. */
+export class EnvelopeAlreadyHeldError extends Error {
+    name = "EnvelopeAlreadyHeldError";
+    constructor(envelopeId) {
+        super(`delivery: envelope ${JSON.stringify(envelopeId)} is already held`);
+    }
+}
+/** Sentinel error: envelope is not in the held queue. */
+export class EnvelopeNotHeldError extends Error {
+    name = "EnvelopeNotHeldError";
+    constructor(envelopeId) {
+        super(`delivery: envelope ${JSON.stringify(envelopeId)} is not held`);
+    }
+}
+/**
+ * Staged-delivery runtime. Concurrency-safe within a single JS event
+ * loop (run-to-completion).
+ */
+export class StagedRunner {
+    cfg;
+    heldMap = new Map();
+    constructor(cfg) {
+        if (cfg.deliver === undefined) {
+            throw new Error("delivery: staged runner requires deliver");
+        }
+        if (cfg.suppress === undefined) {
+            throw new Error("delivery: staged runner requires suppress");
+        }
+        if (cfg.complete === undefined) {
+            throw new Error("delivery: staged runner requires complete");
+        }
+        this.cfg = {
+            deliver: cfg.deliver,
+            suppress: cfg.suppress,
+            complete: cfg.complete,
+            stageTimeoutMs: cfg.stageTimeoutMs !== undefined && cfg.stageTimeoutMs > 0
+                ? cfg.stageTimeoutMs
+                : DefaultStageTimeoutMs,
+            now: cfg.now ?? (() => new Date()),
+        };
+    }
+    /**
+     * Register `envelopeId` with `stages` and deliver to the lowest
+     * stage. `stages[i].stage` MUST be monotonically increasing.
+     * Stages with empty `pending_device_ids` are pruned.
+     */
+    async hold(envelopeId, stages) {
+        if (envelopeId === "") {
+            throw new Error("delivery: hold empty envelope_id");
+        }
+        const cleaned = [];
+        for (const s of stages) {
+            if (s.pending_device_ids.length === 0) {
+                continue;
+            }
+            cleaned.push({
+                stage: s.stage,
+                pending_device_ids: s.pending_device_ids.slice(),
+                dispositions: [],
+            });
+        }
+        if (cleaned.length === 0) {
+            throw new Error("delivery: hold partition has no pending devices at any stage");
+        }
+        for (let i = 1; i < cleaned.length; i++) {
+            if (cleaned[i].stage <= cleaned[i - 1].stage) {
+                throw new Error(`delivery: hold stages not monotonically increasing: stage[${i}]=${cleaned[i].stage} <= stage[${i - 1}]=${cleaned[i - 1].stage}`);
+            }
+        }
+        if (this.heldMap.has(envelopeId)) {
+            throw new EnvelopeAlreadyHeldError(envelopeId);
+        }
+        const deadline = isoSecond(new Date(this.cfg.now().getTime() + this.cfg.stageTimeoutMs));
+        const rec = {
+            envelope_id: envelopeId,
+            stages: cleaned,
+            deadline,
+        };
+        this.heldMap.set(envelopeId, rec);
+        try {
+            await this.cfg.deliver(envelopeId, cleaned[0].stage, cleaned[0].pending_device_ids);
+        }
+        catch (err) {
+            // Best-effort cleanup so a retry can re-hold.
+            this.heldMap.delete(envelopeId);
+            throw new Error(`delivery: stage ${cleaned[0].stage} deliver: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Record `d` for `envelopeId`'s current stage per §3.2.5.
+     *
+     * `submitterDeviceId` is the device_id bound to the session that
+     * delivered the disposition; it MUST equal `d.device_id`.
+     *
+     * Idempotent on repeats from the same device — keeps the FIRST
+     * disposition (conservative aggregation).
+     */
+    ingestDisposition(envelopeId, submitterDeviceId, d) {
+        validateDisposition(d);
+        if (submitterDeviceId === "") {
+            throw new Error("delivery: ingest: submitter device_id is required for §3.2.5 authentication");
+        }
+        if (submitterDeviceId !== d.device_id) {
+            throw new Error(`delivery: ingest: submitter ${JSON.stringify(submitterDeviceId)} does not match disposition device_id ${JSON.stringify(d.device_id)} (§3.2.5)`);
+        }
+        const rec = this.heldMap.get(envelopeId);
+        if (rec === undefined) {
+            throw new Error(`delivery: ingest: no held envelope for ${JSON.stringify(envelopeId)}`);
+        }
+        if (rec.stages.length === 0) {
+            throw new Error(`delivery: ingest: envelope ${JSON.stringify(envelopeId)} has no remaining stages`);
+        }
+        const current = rec.stages[0];
+        if (!current.pending_device_ids.includes(d.device_id)) {
+            throw new Error(`delivery: ingest: device ${JSON.stringify(d.device_id)} is not in current stage ${current.stage}'s pending set (§3.2.5)`);
+        }
+        for (const prior of current.dispositions) {
+            if (prior.device_id === d.device_id) {
+                // Idempotent on a repeat: keep the first vote.
+                return;
+            }
+        }
+        current.dispositions.push(d);
+    }
+    /**
+     * Advance every held envelope whose current stage is complete.
+     * Returns the number of envelopes advanced and the first
+     * non-fatal callback error encountered (per-envelope errors do
+     * not abort the tick).
+     */
+    async tick() {
+        const toRun = [];
+        const now = this.cfg.now();
+        for (const [id, rec] of this.heldMap) {
+            if (rec.stages.length === 0) {
+                continue;
+            }
+            const current = rec.stages[0];
+            if (!isStageComplete(current, now, rec.deadline)) {
+                continue;
+            }
+            const outcome = aggregateDispositions(current.dispositions);
+            if (outcome === "suppress") {
+                toRun.push({ envelopeId: id, outcome, stage: current.stage });
+                this.heldMap.delete(id);
+                continue;
+            }
+            // Advance: pop the current stage, deliver to next if any.
+            rec.stages.shift();
+            if (rec.stages.length === 0) {
+                toRun.push({
+                    envelopeId: id,
+                    outcome,
+                    stage: current.stage,
+                    done: true,
+                });
+                this.heldMap.delete(id);
+                continue;
+            }
+            const next = rec.stages[0];
+            rec.deadline = isoSecond(new Date(now.getTime() + this.cfg.stageTimeoutMs));
+            toRun.push({
+                envelopeId: id,
+                outcome,
+                stage: current.stage,
+                nextStage: next.stage,
+                nextDevs: next.pending_device_ids.slice(),
+            });
+        }
+        // Sort so callback order is deterministic across runs.
+        toRun.sort((a, b) => a.envelopeId < b.envelopeId ? -1 : a.envelopeId > b.envelopeId ? 1 : 0);
+        let firstErr;
+        for (const p of toRun) {
+            try {
+                if (p.outcome === "suppress") {
+                    await this.cfg.suppress(p.envelopeId, p.stage);
+                    continue;
+                }
+                if (p.done === true) {
+                    await this.cfg.complete(p.envelopeId);
+                    continue;
+                }
+                await this.cfg.deliver(p.envelopeId, p.nextStage, p.nextDevs);
+            }
+            catch (err) {
+                if (firstErr === undefined) {
+                    firstErr =
+                        err instanceof Error
+                            ? err
+                            : new Error(`staged tick callback: ${String(err)}`);
+                }
+            }
+        }
+        return firstErr === undefined
+            ? { advanced: toRun.length }
+            : { advanced: toRun.length, firstError: firstErr };
+    }
+    /**
+     * Recompute a held envelope's stage partition per §3.2.6 in
+     * response to a delegated device's certificate being updated or
+     * revoked while the envelope is in flight. `newStages` is the
+     * freshly-computed partition (typically the output of
+     * `partitionStages` over the current directory + cert state).
+     *
+     * Carries forward dispositions already collected at the current
+     * stage. Stages strictly below the current stage have already
+     * been processed and are not part of the held entry.
+     */
+    reevaluate(envelopeId, newStages) {
+        if (envelopeId === "") {
+            throw new Error("delivery: reevaluate empty envelope_id");
+        }
+        const rec = this.heldMap.get(envelopeId);
+        if (rec === undefined) {
+            throw new EnvelopeNotHeldError(envelopeId);
+        }
+        if (rec.stages.length === 0) {
+            return;
+        }
+        const currentStage = rec.stages[0].stage;
+        const priorDispositions = rec.stages[0].dispositions;
+        const sortedNew = newStages
+            .filter((s) => s.stage >= currentStage)
+            .sort((a, b) => a.stage - b.stage);
+        const rebuilt = [];
+        for (const s of sortedNew) {
+            if (s.pending_device_ids.length === 0) {
+                continue;
+            }
+            rebuilt.push({
+                stage: s.stage,
+                pending_device_ids: s.pending_device_ids.slice(),
+                dispositions: s.stage === currentStage ? priorDispositions.slice() : [],
+            });
+        }
+        if (rebuilt.length === 0) {
+            // No stages remain — let the next tick detect completion.
+            rec.stages = [];
+            return;
+        }
+        rec.stages = rebuilt;
+    }
+    /** Whether `envelopeId` is currently held. */
+    isHeld(envelopeId) {
+        return this.heldMap.has(envelopeId);
+    }
+    /** Number of envelopes currently held. */
+    size() {
+        return this.heldMap.size;
+    }
+}
+function isoSecond(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+//# sourceMappingURL=staged_runner.js.map

package/dist/delivery/staged_runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged_runner.js","sourceRoot":"","sources":["../../src/delivery/staged_runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAIL,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AA6B1B,6DAA6D;AAC7D,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAC/B,IAAI,GAAG,0BAA0B,CAAC;IACpD,YAAY,UAAkB;QAC5B,KAAK,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC3B,IAAI,GAAG,sBAAsB,CAAC;IAChD,YAAY,UAAkB;QAC5B,KAAK,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IACxE,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,YAAY;IACN,GAAG,CAE4B;IAC/B,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEzD,YAAY,GAAuB;QACjC,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,GAAG,GAAG;YACT,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,cAAc,EACZ,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,GAAG,CAAC,cAAc,GAAG,CAAC;gBACxD,CAAC,CAAC,GAAG,CAAC,cAAc;gBACpB,CAAC,CAAC,qBAAqB;YAC3B,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;SACnC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,UAAkB,EAAE,MAAyB;QACtD,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC,kBAAkB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtC,SAAS;YACX,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,kBAAkB,EAAE,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE;gBAChD,YAAY,EAAE,EAAE;aACjB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;QACJ,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,IAAI,OAAO,CAAC,CAAC,CAAE,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,KAAK,EAAE,CAAC;gBAC/C,MAAM,IAAI,KAAK,CACb,6DAA6D,CAAC,KAAK,OAAO,CAAC,CAAC,CAAE,CAAC,KAAK,aAAa,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,KAAK,EAAE,CACnI,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,wBAAwB,CAAC,UAAU,CAAC,CAAC;QACjD,CAAC;QACD,MAAM,QAAQ,GAAG,SAAS,CACxB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAC7D,CAAC;QACF,MAAM,GAAG,GAAe;YACtB,WAAW,EAAE,UAAU;YACvB,MAAM,EAAE,OAAO;YACf,QAAQ;SACT,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CACpB,UAAU,EACV,OAAO,CAAC,CAAC,CAAE,CAAC,KAAK,EACjB,OAAO,CAAC,CAAC,CAAE,CAAC,kBAAkB,CAC/B,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,8CAA8C;YAC9C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,mBAAmB,OAAO,CAAC,CAAC,CAAE,CAAC,KAAK,aAAa,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACpG,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,iBAAiB,CACf,UAAkB,EAClB,iBAAyB,EACzB,CAAc;QAEd,mBAAmB,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,iBAAiB,KAAK,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,6EAA6E,CAC9E,CAAC;QACJ,CAAC;QACD,IAAI,iBAAiB,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,+BAA+B,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,yCAAyC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAChJ,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,0CAA0C,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CACvE,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,0BAA0B,CACnF,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CACb,4BAA4B,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,4BAA4B,OAAO,CAAC,KAAK,yBAAyB,CAC1H,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC;gBACpC,+CAA+C;gBAC/C,OAAO;YACT,CAAC;QACH,CAAC;QACD,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QASR,MAAM,KAAK,GAAc,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QAE3B,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,SAAS;YACX,CAAC;YACD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC;YAC/B,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjD,SAAS;YACX,CAAC;YACD,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC5D,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC9D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,0DAA0D;YAC1D,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC;oBACT,UAAU,EAAE,EAAE;oBACd,OAAO;oBACP,KAAK,EAAE,OAAO,CAAC,KAAK;oBACpB,IAAI,EAAE,IAAI;iBACX,CAAC,CAAC;gBACH,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACxB,SAAS;YACX,CAAC;YACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC;YAC5B,GAAG,CAAC,QAAQ,GAAG,SAAS,CACtB,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAClD,CAAC;YACF,KAAK,CAAC,IAAI,CAAC;gBACT,UAAU,EAAE,EAAE;gBACd,OAAO;gBACP,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,SAAS,EAAE,IAAI,CAAC,KAAK;gBACrB,QAAQ,EAAE,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE;aAC1C,CAAC,CAAC;QACL,CAAC;QAED,uDAAuD;QACvD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAClB,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACvE,CAAC;QAEF,IAAI,QAA2B,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,IAAI,CAAC,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;oBAC7B,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;oBAC/C,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACpB,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;oBACtC,SAAS;gBACX,CAAC;gBACD,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,SAAU,EAAE,CAAC,CAAC,QAAS,CAAC,CAAC;YAClE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,QAAQ;wBACN,GAAG,YAAY,KAAK;4BAClB,CAAC,CAAC,GAAG;4BACL,CAAC,CAAC,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,KAAK,SAAS;YAC3B,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE;YAC5B,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvD,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAAC,UAAkB,EAAE,SAA4B;QACzD,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC;QAC1C,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,YAAY,CAAC;QAEtD,MAAM,SAAS,GAAG,SAAS;aACxB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,YAAY,CAAC;aACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAErC,MAAM,OAAO,GAAsB,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,kBAAkB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtC,SAAS;YACX,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,kBAAkB,EAAE,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE;gBAChD,YAAY,EACV,CAAC,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;aAC5D,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,0DAA0D;YAC1D,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC;IACvB,CAAC;IAED,8CAA8C;IAC9C,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAED,0CAA0C;IAC1C,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED,SAAS,SAAS,CAAC,CAAO;IACxB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACnD,CAAC"}

package/dist/delivery/submission.d.ts

@@ -0,0 +1,72 @@
+/**
+ * SEMP_SUBMISSION wire shapes per CLIENT.md §6.1, §6.5 and
+ * DELIVERY.md §2.7.
+ *
+ * `SubmissionResponse` is the synchronous outcome a home server
+ * returns to a client after the client submits an envelope.
+ * `SubmissionEvent` is the asynchronous follow-up notification a
+ * server sends when a previously-queued envelope's outcome resolves.
+ *
+ * @module
+ */
+import type { Acknowledgment } from "./ack.js";
+import type { DeliveryReceipt } from "./receipt.js";
+/** Wire-level type discriminator. */
+export declare const SubmissionType = "SEMP_SUBMISSION";
+/** Schema version. */
+export declare const SubmissionVersion = "1.0.0";
+/**
+ * Discriminator for which submission message variant this is.
+ * `cancel` and `cancel_response` are added by the cancel module
+ * per DELIVERY.md §2.7.
+ */
+export type SubmissionStep = "response" | "event" | "cancel" | "cancel_response";
+/** Per-recipient delivery outcome per CLIENT.md §6.2. */
+export interface SubmissionResult {
+    recipient: string;
+    status: Acknowledgment | "queued" | "no_receipt";
+    reason_code?: string;
+    reason?: string;
+    /**
+     * Populated when `status === "delivered"` per DELIVERY.md
+     * §1.1.1.5; `null` otherwise. Sender-side servers MUST verify
+     * before treating the result as terminal delivered (§1.1.1.6).
+     */
+    receipt?: DeliveryReceipt | null;
+}
+/** SEMP_SUBMISSION response per CLIENT.md §6.1. */
+export interface SubmissionResponse {
+    type: typeof SubmissionType;
+    step: "response";
+    version: string;
+    envelope_id: string;
+    /** ISO 8601 UTC. */
+    timestamp: string;
+    results: SubmissionResult[];
+}
+/** Construct a {@link SubmissionResponse}. */
+export declare function newSubmissionResponse(envelopeId: string, results: SubmissionResult[], nowFn?: () => Date): SubmissionResponse;
+/**
+ * Asynchronous follow-up sent when a queued envelope's outcome
+ * resolves per CLIENT.md §6.5. Single per-recipient event rather
+ * than a batch.
+ */
+export interface SubmissionEvent {
+    type: typeof SubmissionType;
+    step: "event";
+    version: string;
+    envelope_id: string;
+    recipient: string;
+    status: Acknowledgment | "queued" | "no_receipt";
+    reason_code?: string;
+    reason?: string;
+    /** ISO 8601 UTC. */
+    timestamp: string;
+}
+/** Construct a {@link SubmissionEvent}. */
+export declare function newSubmissionEvent(envelopeId: string, recipient: string, status: SubmissionEvent["status"], opts?: {
+    reason_code?: string;
+    reason?: string;
+    nowFn?: () => Date;
+}): SubmissionEvent;
+//# sourceMappingURL=submission.d.ts.map

package/dist/delivery/submission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submission.d.ts","sourceRoot":"","sources":["../../src/delivery/submission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,qCAAqC;AACrC,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD,sBAAsB;AACtB,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,iBAAiB,CAAC;AAEtB,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,YAAY,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAClC;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,cAAc,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,8CAA8C;AAC9C,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,KAAK,GAAE,MAAM,IAAuB,GACnC,kBAAkB,CAYpB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,cAAc,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,YAAY,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2CAA2C;AAC3C,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,EACjC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GACvE,eAAe,CAuBjB"}

package/dist/delivery/submission.js

@@ -0,0 +1,58 @@
+/**
+ * SEMP_SUBMISSION wire shapes per CLIENT.md §6.1, §6.5 and
+ * DELIVERY.md §2.7.
+ *
+ * `SubmissionResponse` is the synchronous outcome a home server
+ * returns to a client after the client submits an envelope.
+ * `SubmissionEvent` is the asynchronous follow-up notification a
+ * server sends when a previously-queued envelope's outcome resolves.
+ *
+ * @module
+ */
+/** Wire-level type discriminator. */
+export const SubmissionType = "SEMP_SUBMISSION";
+/** Schema version. */
+export const SubmissionVersion = "1.0.0";
+/** Construct a {@link SubmissionResponse}. */
+export function newSubmissionResponse(envelopeId, results, nowFn = () => new Date()) {
+    if (envelopeId === "") {
+        throw new Error("delivery: empty envelope_id");
+    }
+    return {
+        type: SubmissionType,
+        step: "response",
+        version: SubmissionVersion,
+        envelope_id: envelopeId,
+        timestamp: isoSecond(nowFn()),
+        results,
+    };
+}
+/** Construct a {@link SubmissionEvent}. */
+export function newSubmissionEvent(envelopeId, recipient, status, opts = {}) {
+    if (envelopeId === "") {
+        throw new Error("delivery: empty envelope_id");
+    }
+    if (recipient === "") {
+        throw new Error("delivery: empty recipient");
+    }
+    const ev = {
+        type: SubmissionType,
+        step: "event",
+        version: SubmissionVersion,
+        envelope_id: envelopeId,
+        recipient,
+        status,
+        timestamp: isoSecond((opts.nowFn ?? (() => new Date()))()),
+    };
+    if (opts.reason_code !== undefined) {
+        ev.reason_code = opts.reason_code;
+    }
+    if (opts.reason !== undefined) {
+        ev.reason = opts.reason;
+    }
+    return ev;
+}
+function isoSecond(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+//# sourceMappingURL=submission.js.map

package/dist/delivery/submission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submission.js","sourceRoot":"","sources":["../../src/delivery/submission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,qCAAqC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAEhD,sBAAsB;AACtB,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAsCzC,8CAA8C;AAC9C,MAAM,UAAU,qBAAqB,CACnC,UAAkB,EAClB,OAA2B,EAC3B,QAAoB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAEpC,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,iBAAiB;QAC1B,WAAW,EAAE,UAAU;QACvB,SAAS,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO;KACR,CAAC;AACJ,CAAC;AAoBD,2CAA2C;AAC3C,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,SAAiB,EACjB,MAAiC,EACjC,OAAsE,EAAE;IAExE,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,EAAE,GAAoB;QAC1B,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,iBAAiB;QAC1B,WAAW,EAAE,UAAU;QACvB,SAAS;QACT,MAAM;QACN,SAAS,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC;IACF,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,EAAE,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IACpC,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,SAAS,CAAC,CAAO;IACxB,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACnD,CAAC"}