@fungi.computer/carrier 0.0.0-stage → 0.1.0

package/docs/api/index.md

@@ -0,0 +1,343 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / index
+
+# index
+
+## Classes
+
+### CarrierError
+
+Stable failures omit email bodies, tokens and raw provider errors.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `code`: `"conflict"` \|
+  `"invalid_input"` \| `"unavailable"`; `message`: `string`; \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CarrierError(code): CarrierError;
+```
+
+###### Parameters
+
+| Parameter | Type                                                 |
+| --------- | ---------------------------------------------------- |
+| `code`    | `"conflict"` \| `"invalid_input"` \| `"unavailable"` |
+
+###### Returns
+
+[`CarrierError`](#carriererror)
+
+###### Overrides
+
+```ts
+Data.TaggedError("CarrierError")<{
+  readonly code: "invalid_input" | "conflict" | "unavailable";
+  readonly message: string;
+}>.constructor
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "conflict" | "invalid_input" | "unavailable";
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CarrierError").code;
+```
+
+##### message
+
+```ts
+message: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CarrierError").message;
+```
+
+## Type Aliases
+
+### Carrier
+
+```ts
+type Carrier = Readonly<{
+  send: (submission) => Promise<Receipt>;
+  get: (id) => Promise<Receipt | undefined>;
+  tick: () => Promise<void>;
+  hasPendingWork: () => Promise<boolean>;
+}>;
+```
+
+Durable email submission and its host-driven recovery door.
+
+---
+
+### Address
+
+```ts
+type Address =
+  | string
+  | Readonly<{
+      email: string;
+      name: string;
+    }>;
+```
+
+One recipient address; display names remain part of the requested envelope.
+
+---
+
+### Email
+
+```ts
+type Email = Readonly<{
+  from: Address;
+  to?: readonly Address[];
+  cc?: readonly Address[];
+  bcc?: readonly Address[];
+  subject: string;
+  html?: string;
+  text?: string;
+  headers?: Readonly<Record<string, string>>;
+}>;
+```
+
+Common content and envelope for one Email.
+
+---
+
+### Submission
+
+```ts
+type Submission = Email &
+  Readonly<{
+    id: string;
+    sendBefore?: number;
+  }>;
+```
+
+Source identity and expiry belong to the notification's producer.
+
+---
+
+### Message
+
+```ts
+type Message = Readonly<{
+  id: string;
+  recipient: string;
+  roles: readonly ("to" | "cc" | "bcc")[];
+  status: "unconfirmed";
+}>;
+```
+
+A recipient Message is distinct from its Email and provider request.
+
+---
+
+### ProviderRejection
+
+```ts
+type ProviderRejection = Readonly<{
+  code: string;
+  class: "permanent" | "temporary";
+}>;
+```
+
+A provider's definite refusal of a whole request: retryable or final.
+
+---
+
+### Receipt
+
+```ts
+type Receipt = Readonly<{
+  id: string;
+  status: Schema.Schema.Type<typeof CarrierStatusSchema>;
+  providerMessageId?: string;
+  providerRejection?: ProviderRejection;
+  messages: readonly Message[];
+}>;
+```
+
+Durable submission and aggregate dispatch evidence, without credential content.
+`refused` means Carrier's per-recipient cap declined the submission before any
+provider attempt; `rejected` means the provider definitely refused it (a
+permanent rejection, or temporary rejections until retries ran out).
+`providerRejection` is the last provider refusal, also while a temporary
+rejection waits `queued` for its retry.
+
+---
+
+### SendEvidence
+
+```ts
+type SendEvidence =
+  | Readonly<{
+      kind: "provider_accepted";
+      providerMessageId: string;
+    }>
+  | (Readonly<{
+      kind: "provider_rejected";
+    }> &
+      ProviderRejection)
+  | Readonly<{
+      kind: "outcome_unknown";
+      cause?: string;
+    }>;
+```
+
+One transport invocation reports only the evidence it obtained. Report
+`provider_rejected` only for a documented refusal of the whole request before
+acceptance; `cause` is an optional sanitized provider code for logs.
+
+---
+
+### Host
+
+```ts
+type Host = Readonly<{
+  commit: <A>(mutation) => Promise<A>;
+  requestWake: () => Promise<void>;
+}>;
+```
+
+Mechanical host capabilities; commit must durably arm a wake with its mutation.
+
+---
+
+### Options
+
+```ts
+type Options = Readonly<{
+  storage: WatchdogSqliteOwner;
+  host: Host;
+  now: () => number;
+  canSend?: (emailId) => Promise<boolean>;
+  transport: (email) => Promise<SendEvidence>;
+}>;
+```
+
+Configure a durable owner; business validity remains with the source.
+
+## Variables
+
+### CarrierStatusSchema
+
+```ts
+const CarrierStatusSchema: Literals<
+  readonly [
+    "queued",
+    "dispatching",
+    "provider_accepted",
+    "outcome_unknown",
+    "rejected",
+    "refused",
+    "expired",
+    "superseded",
+  ]
+>;
+```
+
+Carrier's aggregate dispatch states at both storage and read boundaries.
+
+## Functions
+
+### createCarrier()
+
+```ts
+function createCarrier(options): Promise<Readonly<{
+  send: (submission) => Promise<Readonly<{
+     id: string;
+     status:   | "expired"
+        | "rejected"
+        | "queued"
+        | "outcome_unknown"
+        | "dispatching"
+        | "provider_accepted"
+        | "refused"
+        | "superseded";
+     providerMessageId?: string;
+     providerRejection?: Readonly<{
+        code: string;
+        class: ... | ...;
+     }>;
+     messages: readonly Readonly<{
+        id: string;
+        recipient: string;
+        roles: readonly ...[];
+        status: "unconfirmed";
+     }>[];
+  }>>;
+  get: (id) => Promise<
+     | Readonly<{
+     id: string;
+     status:   | "expired"
+        | "rejected"
+        | "queued"
+        | "outcome_unknown"
+        | "dispatching"
+        | "provider_accepted"
+        | "refused"
+        | "superseded";
+     providerMessageId?: string;
+     providerRejection?: Readonly<{
+        code: ...;
+        class: ...;
+     }>;
+     messages: readonly Readonly<{
+        id: ...;
+        recipient: ...;
+        roles: ...;
+        status: ...;
+     }>[];
+   }>
+    | undefined>;
+  tick: () => Promise<void>;
+  hasPendingWork: () => Promise<boolean>;
+}>>;
+```
+
+Construct exactly one owner per store/runtime lifetime. A replacement may be
+opened only after its predecessor has stopped; simultaneous owners of the same
+store are unsupported. Native adapters supply their runtime ownership.
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `options` | [`Options`](#options) |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `send`: (`submission`) => `Promise`\<`Readonly`\<\{
+`id`: `string`; `status`: \| `"expired"` \| `"rejected"` \| `"queued"` \|
+`"outcome_unknown"` \| `"dispatching"` \| `"provider_accepted"` \| `"refused"`
+\| `"superseded"`; `providerMessageId?`: `string`; `providerRejection?`:
+`Readonly`\<\{ `code`: `string`; `class`: ... \| ...; \}\>; `messages`: readonly
+`Readonly`\<\{ `id`: `string`; `recipient`: `string`; `roles`: readonly ...[];
+`status`: `"unconfirmed"`; \}\>[]; \}\>\>; `get`: (`id`) => `Promise`\< \|
+`Readonly`\<\{ `id`: `string`; `status`: \| `"expired"` \| `"rejected"` \|
+`"queued"` \| `"outcome_unknown"` \| `"dispatching"` \| `"provider_accepted"` \|
+`"refused"` \| `"superseded"`; `providerMessageId?`: `string`;
+`providerRejection?`: `Readonly`\<\{ `code`: ...; `class`: ...; \}\>;
+`messages`: readonly `Readonly`\<\{ `id`: ...; `recipient`: ...; `roles`: ...;
+`status`: ...; \}\>[]; \}\> \| `undefined`\>; `tick`: () => `Promise`\<`void`\>;
+`hasPendingWork`: () => `Promise`\<`boolean`\>; \}\>\>

package/docs/api/inspection.md

@@ -0,0 +1,281 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / inspection
+
+# inspection
+
+## Classes
+
+### DeliveryInspectionError
+
+Stable inspection errors never include stored cargo or raw SQL failures.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new DeliveryInspectionError(code): DeliveryInspectionError;
+```
+
+###### Parameters
+
+| Parameter | Type                                 |
+| --------- | ------------------------------------ |
+| `code`    | `"unavailable"` \| `"invalid_query"` |
+
+###### Returns
+
+[`DeliveryInspectionError`](#deliveryinspectionerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "unavailable" | "invalid_query";
+```
+
+## Type Aliases
+
+### DeliveryInspectionPageQuery
+
+```ts
+type DeliveryInspectionPageQuery = Schema.Codec.Encoded<
+  typeof DeliveryInspectionPageQuerySchema
+>;
+```
+
+An email receipt page uses the same producer-key pagination.
+
+---
+
+### DeliveryInspectionQuery
+
+```ts
+type DeliveryInspectionQuery = Schema.Codec.Encoded<
+  typeof DeliveryInspectionQuerySchema
+>;
+```
+
+Input to one producer-local inspection. Cursors are producer keys, without
+storage prefixes.
+
+---
+
+### PostReceiptSummary
+
+```ts
+type PostReceiptSummary = Schema.Schema.Type<typeof PostReceiptSummarySchema>;
+```
+
+Metadata for one retained Post row.
+
+---
+
+### PostInspectionPage
+
+```ts
+type PostInspectionPage = Schema.Schema.Type<typeof PostInspectionPageSchema>;
+```
+
+One read of producer-local Post dispatch evidence.
+
+---
+
+### CarrierInspectionPage
+
+```ts
+type CarrierInspectionPage = Schema.Schema.Type<
+  typeof CarrierInspectionPageSchema
+>;
+```
+
+One read of aggregate email dispatch evidence.
+
+## Variables
+
+### DeliveryInspectionPageQuerySchema
+
+```ts
+const DeliveryInspectionPageQuerySchema: Struct<{
+  limit: withDecodingDefaultType<Int, never>;
+  after: optional<String>;
+}>;
+```
+
+One bounded scan; an empty filtered page can still have a continuation.
+
+---
+
+### DeliveryInspectionQuerySchema
+
+```ts
+const DeliveryInspectionQuerySchema: Struct<{
+  limit: withDecodingDefaultType<Int, never>;
+  after: optional<String>;
+  view: Literals<readonly ["receipts", "deadLetters"]>;
+}>;
+```
+
+Post can filter dead letters while scanning at most one bounded page.
+
+---
+
+### PostReceiptSummarySchema
+
+```ts
+const PostReceiptSummarySchema: Union<
+  readonly [
+    Struct<{
+      key: String;
+      state: Literal<"delivered">;
+    }>,
+    Struct<{
+      key: String;
+      state: Literal<"pending">;
+      kind: String;
+      attempts: Int;
+      nextAttemptAt: Number;
+    }>,
+    Struct<{
+      key: String;
+      state: Literal<"dead">;
+      kind: String;
+      attempts: Int;
+      reason: Literals<readonly ["refused", "exhausted"]>;
+    }>,
+  ]
+>;
+```
+
+Dispatch evidence deliberately omits the address and event.
+
+---
+
+### PostInspectionPageSchema
+
+```ts
+const PostInspectionPageSchema: Union<readonly [Struct<{
+  status: Literal<"uninitialized">;
+}>, Struct<{
+  status: Literal<"available">;
+  records: $Array<Union<readonly [Struct<{
+     key: String;
+     state: Literal<"delivered">;
+   }>, Struct<{
+     key: String;
+     state: Literal<"pending">;
+     kind: String;
+     attempts: Int;
+     nextAttemptAt: Number;
+   }>, Struct<{
+     key: String;
+     state: Literal<"dead">;
+     kind: String;
+     attempts: Int;
+     reason: Literals<readonly [..., ...]>;
+  }>]>>;
+  nextCursor: NullOr<String>;
+}>]>;
+```
+
+Bounded evidence with an explicit distinction between empty and uninitialized
+storage.
+
+---
+
+### CarrierReceiptSummarySchema
+
+```ts
+const CarrierReceiptSummarySchema: Struct<{
+  id: String;
+  status: Literals<
+    readonly [
+      "queued",
+      "dispatching",
+      "provider_accepted",
+      "outcome_unknown",
+      "rejected",
+      "refused",
+      "expired",
+      "superseded",
+    ]
+  >;
+  attempts: Int;
+  retryAt: NullOr<Number>;
+  providerMessageId: optional<NonEmptyString>;
+  providerRejection: optional<
+    Struct<{
+      code: NonEmptyString;
+      class: Literals<readonly ["permanent", "temporary"]>;
+    }>
+  >;
+}>;
+```
+
+Aggregate email evidence without bodies, headers or recipient addresses.
+
+---
+
+### CarrierInspectionPageSchema
+
+```ts
+const CarrierInspectionPageSchema: Union<readonly [Struct<{
+  status: Literal<"uninitialized">;
+}>, Struct<{
+  status: Literal<"available">;
+  records: $Array<Struct<{
+     id: String;
+     status: Literals<readonly ["queued", "dispatching", "provider_accepted", "outcome_unknown", "rejected", "refused", "expired", "superseded"]>;
+     attempts: Int;
+     retryAt: NullOr<Number>;
+     providerMessageId: optional<NonEmptyString>;
+     providerRejection: optional<Struct<{
+        code: NonEmptyString;
+        class: Literals<...>;
+     }>>;
+  }>>;
+  nextCursor: NullOr<String>;
+}>]>;
+```
+
+Carrier's bounded metadata page; unavailable storage is never reported as empty.
+
+## Functions
+
+### createDeliveryInspection()
+
+```ts
+function createDeliveryInspection(sql): object;
+```
+
+Read existing storage without opening a sender, initializing tables, repairing
+jobs or arming a wake. The trusted host must admit an operator before calling.
+
+#### Parameters
+
+| Parameter | Type                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `sql`     | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\> |
+
+#### Returns
+
+| Name      | Type                                                                                                                                                                                                                                                                                                                                                                                                                                               | Description                                                                        |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `email()` | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly `object`[]; `nextCursor`: `string` \| `null`; \}                                                                                                                                                                                                                                                                                             | Read aggregate dispatch evidence without email cargo or recipient addresses.       |
+| `post()`  | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly ( \| \{ `key`: `string`; `state`: `"delivered"`; \} \| \{ `key`: `string`; `state`: `"pending"`; `kind`: `string`; `attempts`: `number`; `nextAttemptAt`: `number`; \} \| \{ `key`: `string`; `state`: `"dead"`; `kind`: `string`; `attempts`: `number`; `reason`: `"refused"` \| `"exhausted"`; \})[]; `nextCursor`: `string` \| `null`; \} | Read Post metadata; filtered pages retain their continuation through other states. |