@fungi.computer/carrier 0.0.0-stage → 0.0.1

package/docs/api/cloudflare.md

@@ -0,0 +1,100 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / cloudflare
+
+# cloudflare
+
+## Type Aliases
+
+### CloudflareCarrierStorage
+
+```ts
+type CloudflareCarrierStorage = WatchdogSqliteOwner &
+  Pick<
+    DurableObjectStorage,
+    "transaction" | "getAlarm" | "setAlarm" | "deleteAlarm"
+  >;
+```
+
+Native SQLite and alarms; the Cloudflare adapter owns their atomic composition.
+
+---
+
+### CloudflareCarrierOptions
+
+```ts
+type CloudflareCarrierOptions = Readonly<{
+  storage: CloudflareCarrierStorage;
+  canSend?: (emailId) => Promise<boolean>;
+}> &
+  | Readonly<{
+  email: SendEmail;
+  transport?: never;
+}>
+  | Readonly<{
+  transport: Options["transport"];
+  email?: never;
+}>;
+```
+
+Native storage/wake composition with exactly one provider capability.
+
+---
+
+### CloudflareCarrier
+
+```ts
+type CloudflareCarrier = Pick<Carrier, "send" | "get"> &
+  Readonly<{
+    alarm: () => Promise<void>;
+  }>;
+```
+
+Ordinary submission operations and the native Durable Object alarm door.
+
+## Functions
+
+### createCloudflareCarrier()
+
+```ts
+function createCloudflareCarrier(options): Promise<CloudflareCarrier>;
+```
+
+Construct one owner per Durable Object. Forward its native alarm to `alarm`.
+Acceptance commits the Email, recipient Messages, Watchdog job and wake
+together.
+
+#### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `options` | [`CloudflareCarrierOptions`](#cloudflarecarrieroptions) |
+
+#### Returns
+
+`Promise`\<[`CloudflareCarrier`](#cloudflarecarrier)\>
+
+---
+
+### cloudflareEmailTransport()
+
+```ts
+function cloudflareEmailTransport(binding): (email) => Promise<SendEvidence>;
+```
+
+The native binding as a Carrier transport. Exported so a host that holds the
+binding elsewhere (the Hub's Cloudflare edge) classifies sends identically.
+
+#### Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `binding` | `SendEmail` |
+
+#### Returns
+
+(`email`) => `Promise`\<[`SendEvidence`](index.md#sendevidence)\>

package/docs/api/email.md

@@ -0,0 +1,87 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / email
+
+# email
+
+## References
+
+### CarrierError
+
+Re-exports [CarrierError](index.md#carriererror)
+
+---
+
+### CarrierStatusSchema
+
+Re-exports [CarrierStatusSchema](index.md#carrierstatusschema)
+
+---
+
+### Address
+
+Re-exports [Address](index.md#address)
+
+---
+
+### Email
+
+Re-exports [Email](index.md#email)
+
+---
+
+### Host
+
+Re-exports [Host](index.md#host)
+
+---
+
+### Message
+
+Re-exports [Message](index.md#message)
+
+---
+
+### Options
+
+Re-exports [Options](index.md#options)
+
+---
+
+### ProviderRejection
+
+Re-exports [ProviderRejection](index.md#providerrejection)
+
+---
+
+### Receipt
+
+Re-exports [Receipt](index.md#receipt)
+
+---
+
+### SendEvidence
+
+Re-exports [SendEvidence](index.md#sendevidence)
+
+---
+
+### Submission
+
+Re-exports [Submission](index.md#submission)
+
+---
+
+### Carrier
+
+Re-exports [Carrier](index.md#carrier)
+
+---
+
+### createCarrier
+
+Re-exports [createCarrier](index.md#createcarrier)

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`\>; \}\>\>