humanish 0.95.0 → 0.96.1

package/dist/comms-receiving-types.d.ts

@@ -0,0 +1,98 @@
+/** Internal receiving-only contract. Provider identifiers and content are host/runtime-only. */
+import type { CommsInlineImage } from "./comms-types.js";
+export interface ReceivingContext {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface ReceivingIdentity {
+    provider: "agentmail";
+    accountId: string;
+    scopeType: "organization" | "pod" | "inbox";
+    scopeId: string;
+}
+export interface ReceivingLease {
+    resourceId: string;
+    address: string;
+    clientId: string;
+}
+export interface ReceivedEmail {
+    channel: "email";
+    providerMessageId: string;
+    providerTimestamp?: string;
+    from: string;
+    subject?: string;
+    text: string;
+    html?: string;
+    inlineImages: CommsInlineImage[];
+    limitations: string[];
+}
+export interface ReceivingBatch {
+    messages: ReceivedEmail[];
+    complete: boolean;
+    /** Stable safe codes only, never provider error bodies or identifiers. */
+    limitations: string[];
+}
+export interface ReceivingAdapter {
+    readonly provider: "agentmail";
+    authenticate(context?: ReceivingContext): Promise<ReceivingIdentity>;
+    acquire(clientId: string, context?: ReceivingContext): Promise<ReceivingLease>;
+    read(lease: ReceivingLease, context?: ReceivingContext): Promise<ReceivingBatch>;
+    release(lease: ReceivingLease, context?: ReceivingContext): Promise<{
+        status: "absent" | "deleting";
+    }>;
+}
+/** Content provided to a single participant's desktop; no provider identifiers. */
+export interface ParticipantEmail extends Omit<ReceivedEmail, "providerMessageId"> {
+    id: string;
+}
+export interface ReceivingSurfaceFile {
+    path: string;
+    body: string;
+    contentType: "text/html; charset=utf-8" | "application/json; charset=utf-8";
+}
+export interface RenderedReceivingInbox {
+    files: ReceivingSurfaceFile[];
+    blockedAssetCount: number;
+    blockedLinkCount: number;
+    /** Register before publishing; never persist this array. */
+    secrets: string[];
+    linkCount: number;
+    codeCount: number;
+}
+export interface ReceivingSurface {
+    url: string;
+    publish(files: ReceivingSurfaceFile[]): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare const COMMS_RECEIVING_SCHEMA = "humanish.comms-receiving.v2";
+export interface ReceivingMessageEvidence {
+    id: string;
+    firstObservedAt: string;
+    providerTimestamp?: string;
+    publishedAt?: string;
+}
+export interface ReceivingParticipantEvidence {
+    participantId: string;
+    leaseId: string;
+    acquisition: "pending" | "active" | "failed";
+    cleanup: "pending" | "absent" | "deleting" | "unresolved";
+    observed: number;
+    published: number;
+    linkCount: number;
+    codeCount: number;
+    blockedAssetCount: number;
+    blockedLinkCount: number;
+    messages: ReceivingMessageEvidence[];
+    limitations: string[];
+}
+export interface CommsReceivingEvidence {
+    schema: typeof COMMS_RECEIVING_SCHEMA;
+    channel: "email";
+    provider: "agentmail";
+    publication: "restricted-real-communications";
+    state: "acquiring" | "running" | "finished";
+    participants: ReceivingParticipantEvidence[];
+    limitations: string[];
+    /** Inbox links are constrained; the rest of the browser is not network-confined. */
+    browserConfinement: "mail-surface-only";
+}

package/dist/comms-receiving-types.js

@@ -0,0 +1,2 @@
+export const COMMS_RECEIVING_SCHEMA = "humanish.comms-receiving.v2";
+//# sourceMappingURL=comms-receiving-types.js.map

package/dist/comms-receiving-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-receiving-types.js","sourceRoot":"","sources":["../src/comms-receiving-types.ts"],"names":[],"mappings":"AAsDA,MAAM,CAAC,MAAM,sBAAsB,GAAG,6BAA6B,CAAC"}

package/dist/comms-receiving.d.ts

@@ -0,0 +1,58 @@
+/** Run-scoped real-email receiving. Resource authority and message content stay on the host. */
+import { type CommsRecoveryEntry } from "./comms-lease-store.js";
+import { type CommsReceivingEvidence, type ParticipantEmail, type ReceivingAdapter, type ReceivingSurface, type RenderedReceivingInbox } from "./comms-receiving-types.js";
+export type { CommsRecoveryEntry } from "./comms-lease-store.js";
+export declare class CommsReceivingError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+type RenderInput = {
+    address: string;
+    messages: ParticipantEmail[];
+    allowedOrigins: string[];
+    originMap?: Array<[string, string]>;
+};
+export interface StartCommsReceivingOptions {
+    cwd: string;
+    runId: string;
+    connectionName: string;
+    apiKeyEnv: string;
+    adapter: ReceivingAdapter;
+    participants: string[];
+    writeEvidence: (evidence: CommsReceivingEvidence) => Promise<void>;
+    registerSecrets: (secrets: string[]) => void;
+    render: (input: RenderInput) => RenderedReceivingInbox;
+    signal?: AbortSignal;
+    stateDir?: string;
+}
+export interface CommsReceivingRun {
+    address(participantId: string): string;
+    attach(participantId: string, options: {
+        surface: ReceivingSurface;
+        allowedOrigins: string[];
+        originMap?: Array<[string, string]>;
+    }): Promise<void>;
+    finishParticipant(participantId: string): Promise<void>;
+    finish(): Promise<CommsReceivingEvidence>;
+    snapshot(): CommsReceivingEvidence;
+}
+export declare function startCommsReceiving(options: StartCommsReceivingOptions): Promise<CommsReceivingRun>;
+/** Side-effect-free local inspection: does not authenticate, enumerate provider resources or replay creation. */
+export declare function inspectCommsRecovery(options: {
+    cwd: string;
+    stateDir?: string;
+}): Promise<CommsRecoveryEntry[]>;
+/** Explicit mutation: may replay an uncertain original create, then immediately dispose that exact resource. */
+export declare function recoverCommsReceiving(options: {
+    cwd: string;
+    runId: string;
+    connectionName: string;
+    apiKeyEnv: string;
+    adapter: ReceivingAdapter;
+    stateDir?: string;
+}): Promise<{
+    ok: boolean;
+    recovered: number;
+    unresolved: number;
+    message: string;
+}>;