better-supabase 0.5.0 → 0.6.0

package/dist/chat-sdk/index.d.ts

@@ -0,0 +1,303 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../result-D7y2fT87.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../block-transport-DvaoPuZ9.js";
+import { a as CredentialSubject, i as CredentialRef, o as CredentialToken, r as CredentialProvider } from "../provider-BH5UWZJ6.js";
+import { o as StreamStore } from "../store-CGjgWu5n.js";
+import { C as InboxMessage, T as MessageAttachment, a as Inbox, b as InboundResult, h as Conversation, j as StoredInboundEvent, y as DeliveryStatus } from "../inbox-i7E1ppo6.js";
+import { Adapter, AdapterPostableMessage, Attachment, Message, RawMessage, StateAdapter, WebhookOptions } from "chat";
+//#region src/chat-sdk/delivery.d.ts
+/** One status callback for a message the bot sent on a channel. */
+interface DeliveryUpdate {
+  readonly externalId: string;
+  readonly status: DeliveryStatus;
+  readonly error?: string;
+}
+/**
+ * What a stored webhook body says about deliveries. `only` is true when the
+ * body carries nothing but statuses, so it needs no replay into Chat SDK.
+ */
+interface ParsedDeliveries {
+  readonly updates: readonly DeliveryUpdate[];
+  readonly only: boolean;
+}
+/** Reads delivery statuses from a stored webhook event; `null` when the body is not one it knows. */
+type DeliveryParser = (event: {
+  readonly body: string;
+  readonly headers: Readonly<Record<string, string>>;
+}) => ParsedDeliveries | null;
+/** WhatsApp Cloud API: `entry[].changes[].value.statuses[]`. */
+export declare const whatsappDeliveries: DeliveryParser;
+/** Messenger and Instagram: `entry[].messaging[].delivery.mids`. Read receipts carry no ids and are skipped. */
+export declare const messengerDeliveries: DeliveryParser;
+/** Twilio status callbacks: a form body with `MessageSid` and `MessageStatus` and no `Body`. */
+export declare const twilioDeliveries: DeliveryParser;
+/** The parsers `inboundHandler` uses by default, keyed by adapter name. */
+export declare const DELIVERY_PARSERS: Readonly<Record<string, DeliveryParser>>;
+//#endregion
+//#region src/chat-sdk/channels.d.ts
+/** The parts of a Chat SDK `Chat` the inbox helpers use. */
+interface ChatLike {
+  readonly webhooks: Readonly<Record<string, (request: Request, options?: WebhookOptions) => Promise<Response>>>;
+  getAdapter(name: string): Adapter | undefined;
+  getState(): StateAdapter;
+}
+interface ChannelAdapterOptions<A> {
+  readonly credentials: CredentialProvider;
+  /** The install's `credential_ref`, from `installations.get`. */
+  readonly ref: CredentialRef;
+  readonly subject?: CredentialSubject;
+  /** Builds the platform adapter with the token, e.g. `(t) => createSlackAdapter({ botToken: t.token })`. */
+  readonly create: (token: CredentialToken) => A | Promise<A>;
+}
+/** A platform adapter built from the token the credential provider holds, so no secret sits in env. */
+export declare function channelAdapter<A>(options: ChannelAdapterOptions<A>): Promise<A>;
+interface InboxWebhookOptions {
+  /** `createInbox` on a service transport. */
+  readonly inbox: Inbox;
+  /** The adapter name the event is replayed into later. */
+  readonly adapter: string;
+  readonly inboxId?: string;
+  readonly tenant?: string;
+  /** With `ref`, checks the request with `credentials.verifyInbound` before storing it. */
+  readonly credentials?: CredentialProvider;
+  readonly ref?: CredentialRef;
+  /** Checks the request when no credential ref does. Without either, every request is stored. */
+  readonly verify?: (request: Request, body: string) => boolean | Promise<boolean>;
+  /** The platform's event id, so a retried delivery is stored once. */
+  readonly externalId?: (body: string, request: Request) => string | undefined;
+  /**
+   * Requests the platform answers synchronously, such as Meta's `GET`
+   * verification or Slack's `url_verification`. They go straight to this
+   * handler instead of the store. Defaults to `GET` requests and Slack
+   * challenges, handed to `passthroughHandler`.
+   */
+  readonly passthrough?: (request: Request, body: string) => boolean;
+  readonly passthroughHandler?: (request: Request) => Promise<Response>;
+  /** Runs after the event is stored, e.g. `after(() => handler.drain())`. */
+  readonly after?: (stored: {
+    readonly id: string;
+    readonly duplicate: boolean;
+  }) => void;
+}
+/**
+ * A route handler that verifies a channel webhook, stores the raw event in
+ * the inbox's `inbound_events` and answers 200 at once. `inboundHandler`
+ * replays it into Chat SDK later, so a slow bot never makes the platform
+ * retry.
+ */
+export declare function webhook(options: InboxWebhookOptions): (request: Request) => Promise<Response>;
+/** The thread a Chat SDK handler gets, as much as `mirror` needs. */
+interface MirrorThread {
+  readonly id: string;
+  readonly adapter: {
+    readonly name: string;
+  };
+}
+interface InboundHandlerOptions {
+  readonly chat: ChatLike;
+  /** `createInbox` on a service transport. */
+  readonly inbox: Inbox;
+  /** The inbox each adapter's threads land in, by adapter name. */
+  readonly inboxes: Readonly<Record<string, string>>;
+  /** Delivery status parsers by adapter name. Defaults to WhatsApp, Messenger, Instagram and Twilio. */
+  readonly parsers?: Readonly<Record<string, DeliveryParser>>;
+  /**
+   * Copies a platform file into storage for the inbox. Without it a file
+   * is kept only when it has a public URL; platform URLs often need the
+   * bot's token, so copy them.
+   */
+  readonly copyFile?: (file: Attachment, context: {
+    readonly adapter: string;
+    readonly threadId: string;
+  }) => Promise<MessageAttachment | null>;
+  /** The URL replayed requests carry. Defaults to `https://inbox.local/<adapter>`. */
+  readonly baseUrl?: string;
+}
+interface DrainResult {
+  readonly processed: number;
+  readonly failed: number;
+}
+interface InboundHandler {
+  /** Replays one stored event: delivery statuses go to the inbox, the rest into Chat SDK. */
+  process(event: StoredInboundEvent): Promise<void>;
+  /** Processes pending events, oldest first. */
+  drain(options?: {
+    readonly limit?: number;
+    readonly maxAttempts?: number;
+  }): Promise<DrainResult>;
+  /**
+   * Records a channel message in the inbox, from a Chat SDK handler. Skips
+   * bot messages, its own and the ones `deliver` posted (their echo);
+   * returns `null` for those.
+   */
+  mirror(thread: MirrorThread, message: Message): Promise<InboundResult | null>;
+}
+/** Replays stored webhook events and mirrors channel messages into the inbox. */
+export declare function inboundHandler(options: InboundHandlerOptions): InboundHandler;
+/** The job the `inbox` module queues for a staff reply on a channel inbox. */
+interface InboxOutboundJob {
+  readonly message_id: string;
+  readonly conversation_id: string;
+  readonly inbox_id?: string;
+}
+interface DeliverOptions {
+  readonly chat: ChatLike;
+  /** `createInbox` on a service transport. */
+  readonly inbox: Inbox;
+  /** The adapter that posts a conversation's replies. Defaults to the inbox's channel (`sms` posts with `twilio`). */
+  readonly adapterFor?: (conversation: Conversation) => string;
+  /**
+   * The approved template to send when the channel's reply window is
+   * closed, such as WhatsApp's 24 hours after the contact's last message.
+   * Return `null` to post the message as is.
+   */
+  readonly template?: (context: {
+    readonly conversation: Conversation;
+    readonly message: InboxMessage;
+    readonly adapter: Adapter;
+  }) => Promise<AdapterPostableMessage | null> | AdapterPostableMessage | null;
+}
+/** True while WhatsApp's customer service window is open: within 24 hours of the contact's last message. */
+export declare function whatsappWindowOpen(inbox: Inbox, conversationId: string, now?: Temporal.Instant): Promise<boolean>;
+/**
+ * Posts a staff reply the `inbox` module queued on its channel, records
+ * the delivery with the platform's message id, and remembers the id so
+ * `mirror` skips the platform's echo. A failed post is recorded and thrown,
+ * so the job retries.
+ */
+export declare function deliver(options: DeliverOptions): (job: InboxOutboundJob) => Promise<RawMessage | null>;
+interface MaintainOptions {
+  /** `createInbox` on a service transport. */
+  readonly inbox: Inbox;
+  /** Replays events a crashed request left pending. */
+  readonly handler?: InboundHandler;
+  /** `createSupabaseState(...)`: deletes expired locks, cache rows, lists and queues. */
+  readonly state?: {
+    purge(options?: {
+      readonly batch?: number;
+    }): Promise<number>;
+  };
+  /** How long processed webhook events stay. Defaults to 7 days. */
+  readonly keepEvents?: number | string;
+}
+interface MaintainResult {
+  readonly woken: number;
+  readonly purgedEvents: number;
+  readonly replayed: DrainResult;
+  readonly purgedState: number;
+}
+/** The inbox's periodic work: wake snoozed conversations, replay and purge webhook events, sweep state. Run it from a cron job. */
+export declare function maintain(options: MaintainOptions): Promise<MaintainResult>;
+//#endregion
+//#region src/chat-sdk/inbox-adapter.d.ts
+/** The job the `inbox` module queues for a contact message while `bot_mode = 'bot'`. */
+interface InboxBotJob {
+  readonly conversation_id: string;
+  readonly message_id: string;
+  readonly thread_id?: string;
+  readonly inbox_id?: string;
+}
+interface InboxAdapterOptions {
+  /** `createInbox` on a service transport: the bot writes as the service. */
+  readonly inbox: Inbox;
+  /** The bot's name on its messages and reactions. Defaults to `bot`. */
+  readonly userName?: string;
+  /**
+   * Checks a request `handleWebhook` gets, such as a shared secret or a
+   * signature. Without it `handleWebhook` answers 401; bot jobs go through
+   * `dispatch` instead.
+   */
+  readonly verify?: (request: Request) => boolean | Promise<boolean>;
+  /** Stores streamed replies so a reader can resume them; the stream id lands in the message's `metadata.stream_id`. */
+  readonly streams?: StreamStore;
+}
+interface InboxAdapter extends Adapter<string, InboxMessage> {
+  readonly name: "inbox";
+  /** Hands a queued bot job to Chat SDK: loads the contact's message and runs the bot's handlers. Other authors are skipped. */
+  dispatch(job: InboxBotJob): Promise<void>;
+}
+/** `inbox:<conversation id>` to the conversation id. */
+export declare function conversationIdOf(threadId: string): string;
+/**
+ * A Chat SDK adapter for the in-app inbox: the bot reads and writes the
+ * `inbox` module's conversations, so one `Chat` instance answers the
+ * widget and the other channels. Contact messages reach the bot as jobs
+ * on the module's bot queue; pass them to `dispatch`.
+ */
+export declare function inboxAdapter(options: InboxAdapterOptions): InboxAdapter;
+//#endregion
+//#region src/chat-sdk/installations.d.ts
+/** A workspace, page or number a bot is installed in. */
+interface ChatInstallation {
+  readonly id: string;
+  readonly tenant: string | null;
+  readonly adapter: string;
+  readonly externalId: string;
+  readonly credentialRef: CredentialRef | null;
+  readonly installedBy: string | null;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly installedAt: Temporal.Instant;
+  readonly uninstalledAt: Temporal.Instant | null;
+}
+interface InstallInput {
+  readonly adapter: string;
+  readonly externalId: string;
+  readonly tenant?: string;
+  readonly credentialRef?: CredentialRef;
+  readonly installedBy?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface ChatInstallationsOptions {
+  /** `sqlTransport(postgres.asService())` or `rpcTransport` with the service role key. */
+  readonly transport: BlockTransport;
+  /** Revokes the ref a reinstall replaces and the ref an uninstall clears. */
+  readonly credentials: CredentialProvider;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface ChatInstallations {
+  /** Records an install; a reinstall revokes the credential it replaces. */
+  install(input: InstallInput): AsyncResult<ChatInstallation>;
+  /** Marks the install removed and revokes its credential; false when none was live. */
+  uninstall(adapter: string, externalId: string): AsyncResult<boolean>;
+  /** Uninstalls every live install of a tenant before it is purged; returns how many. */
+  uninstallTenant(tenant: string): AsyncResult<number>;
+  get(adapter: string, externalId: string): AsyncResult<ChatInstallation | null>;
+  list(filter?: {
+    readonly tenant?: string;
+    readonly adapter?: string;
+    readonly includeUninstalled?: boolean;
+  }): AsyncResult<readonly ChatInstallation[]>;
+}
+/**
+ * The `chat_installations` registry with the credential lifecycle: every
+ * ref an install drops is revoked through the `CredentialProvider`.
+ */
+export declare function createChatInstallations(options: ChatInstallationsOptions): ChatInstallations;
+//#endregion
+//#region src/chat-sdk/state.d.ts
+interface SupabaseStateOptions {
+  /** `sqlTransport(postgres.asService())` or `rpcTransport` with the service role key. */
+  readonly transport: BlockTransport;
+  /** The schema of the `chat-sdk-state` module. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Separates bots that share the tables. Defaults to `chat-sdk`. */
+  readonly keyPrefix?: string;
+}
+/** The `StateAdapter` with the prefix it writes under, for tests and sweeps. */
+interface SupabaseState extends StateAdapter {
+  readonly keyPrefix: string;
+  /** Deletes expired rows, at most `batch` of each kind; returns how many went. */
+  purge(options?: {
+    readonly batch?: number;
+  }): Promise<number>;
+}
+/**
+ * A Chat SDK `StateAdapter` on the `chat-sdk-state` SQL module: thread
+ * subscriptions, locks, the cache, lists and the per-thread queue in
+ * Postgres, so a bot needs no Redis. Service role only.
+ */
+export declare function createSupabaseState(options: SupabaseStateOptions): SupabaseState;
+//#endregion
+export { type BlockTransport, type ChannelAdapterOptions, type ChatInstallation, type ChatInstallations, type ChatInstallationsOptions, type ChatLike, type DeliverOptions, type DeliveryParser, type DeliveryUpdate, type DrainResult, type InboundHandler, type InboundHandlerOptions, type InboxAdapter, type InboxAdapterOptions, type InboxBotJob, type InboxOutboundJob, type InboxWebhookOptions, type InstallInput, type MaintainOptions, type MaintainResult, type MirrorThread, type ParsedDeliveries, type SupabaseState, type SupabaseStateOptions, rpcTransport, sqlTransport };