better-supabase 0.8.0 → 0.10.0

package/dist/inbox-BaUJgHOF.d.ts

@@ -0,0 +1,400 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-NbUJygA7.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+//#region src/blocks/inbox/types.d.ts
+/** The channels an inbox can sit on. */
+type InboxChannel = "in_app" | "email" | "slack" | "teams" | "discord" | "telegram" | "whatsapp" | "messenger" | "instagram" | "sms" | "github" | "linear" | "other";
+/** `bot`: the bot answers; `human`: staff answer; `paused`: nobody answers. */
+type BotMode = "bot" | "human" | "paused";
+type ConversationStatus = "open" | "pending" | "snoozed" | "resolved";
+type ConversationPriority = "low" | "normal" | "high" | "urgent";
+type MessageDirection = "inbound" | "outbound";
+type MessageKind = "message" | "note";
+type AuthorType = "contact" | "agent" | "bot" | "system";
+type DeliveryStatus = "queued" | "sent" | "delivered" | "read" | "failed";
+interface InboxRow {
+  readonly id: string;
+  readonly tenant: string;
+  readonly name: string;
+  readonly channel: InboxChannel;
+  readonly address: string | null;
+  readonly installationId: string | null;
+  readonly botMode: BotMode;
+  readonly settings: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+  readonly archivedAt: Temporal.Instant | null;
+}
+interface Contact {
+  readonly id: string;
+  readonly tenant?: string;
+  readonly userId: string | null;
+  readonly name: string | null;
+  readonly email: string | null;
+  readonly phone: string | null;
+  readonly avatarUrl: string | null;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface Conversation {
+  readonly id: string;
+  readonly tenant: string;
+  readonly inboxId: string;
+  readonly contactId: string;
+  readonly subject: string | null;
+  readonly status: ConversationStatus;
+  readonly priority: ConversationPriority;
+  readonly assigneeId: string | null;
+  readonly teamId: string | null;
+  readonly botMode: BotMode;
+  /** The Chat SDK thread id, or `inbox:<id>` for the in-app widget. */
+  readonly threadId: string;
+  readonly snoozedUntil: Temporal.Instant | null;
+  readonly lastMessageAt: Temporal.Instant | null;
+  readonly preview: string | null;
+  readonly firstResponseAt: Temporal.Instant | null;
+  readonly resolvedAt: Temporal.Instant | null;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+  readonly contact: Contact | null;
+  readonly inbox: {
+    readonly id: string;
+    readonly name: string;
+    readonly channel: InboxChannel;
+  } | null;
+  /** When the caller last read it. */
+  readonly lastReadAt: Temporal.Instant | null;
+  /** When the contact last read it; `null` for contacts and before they read. */
+  readonly contactReadAt: Temporal.Instant | null;
+  /** In lists: whether a message arrived after `lastReadAt`. */
+  readonly unread?: boolean;
+}
+interface MessageAttachment {
+  readonly path?: string;
+  readonly url?: string;
+  readonly name?: string;
+  readonly contentType?: string;
+  readonly size?: number;
+}
+interface MessageDelivery {
+  readonly channel: string;
+  readonly status: DeliveryStatus;
+  readonly error: string | null;
+}
+interface InboxMessage {
+  readonly id: string;
+  readonly conversationId: string;
+  readonly direction: MessageDirection;
+  readonly kind: MessageKind;
+  readonly authorType: AuthorType;
+  readonly authorId: string | null;
+  readonly body: string;
+  readonly format: "text" | "markdown";
+  readonly attachments: readonly MessageAttachment[];
+  /** Emoji to the actors (user ids or channel ids) who reacted. */
+  readonly reactions: Readonly<Record<string, readonly string[]>>;
+  readonly mentions: readonly string[];
+  readonly externalId: string | null;
+  readonly replyTo: string | null;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+  readonly editedAt: Temporal.Instant | null;
+  readonly deletedAt: Temporal.Instant | null;
+  readonly delivery?: MessageDelivery | null;
+}
+interface ConversationEvent {
+  readonly id: string;
+  readonly type: string;
+  readonly actorId: string | null;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+}
+interface InboxCounts {
+  readonly open: number;
+  readonly mine: number;
+  readonly unassigned: number;
+  readonly unread: number;
+}
+/** What `purgeContact` erased. */
+interface PurgedContact {
+  readonly conversations: number;
+  readonly messages: number;
+  /** Storage paths of the erased messages' attachments, for the caller to remove. */
+  readonly attachments: readonly string[];
+}
+interface InboundResult {
+  readonly conversationId: string;
+  readonly messageId: string;
+  readonly contactId: string;
+  readonly tenant: string;
+  /** A new conversation was opened for the thread. */
+  readonly created: boolean;
+  /** The message's `externalId` was already stored. */
+  readonly duplicate: boolean;
+}
+interface MessageTemplate {
+  readonly id: string;
+  readonly tenant: string;
+  readonly inboxId: string | null;
+  readonly name: string;
+  readonly channel: string;
+  readonly language: string;
+  readonly body: string;
+  readonly variables: readonly string[];
+  /** The provider's approved template name (WhatsApp). */
+  readonly externalId: string | null;
+}
+interface StoredInboundEvent {
+  readonly id: string;
+  readonly adapter: string;
+  readonly externalId: string | null;
+  readonly inboxId: string | null;
+  readonly tenant: string | null;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly attempts: number;
+  readonly receivedAt: Temporal.Instant;
+}
+//#endregion
+//#region src/blocks/inbox/inbox.d.ts
+interface InboxOptions extends BlockTemporalOptions {
+  /**
+   * `sqlTransport(postgres.asUser(claims))` or `rpcTransport(supabase)` for a
+   * member or a contact; over the service role for webhooks and workers.
+   */
+  readonly transport: BlockTransport;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around the methods (ADR 0015). */
+  readonly hooks?: InboxHooks;
+  /** Receives the errors `after` hooks throw. */
+  readonly logger?: Logger;
+}
+interface CreateInboxInput {
+  readonly tenant: string;
+  readonly name: string;
+  readonly channel?: InboxChannel;
+  /** The channel's address: a phone number, a Slack team id, an email. */
+  readonly address?: string;
+  readonly botMode?: BotMode;
+  /** `widget: true` lets signed-in visitors open conversations in an in-app inbox. */
+  readonly settings?: Readonly<Record<string, unknown>>;
+}
+interface InboxPatch {
+  readonly name?: string;
+  readonly botMode?: BotMode;
+  readonly settings?: Readonly<Record<string, unknown>>;
+  readonly address?: string | null;
+  readonly installationId?: string | null;
+  readonly archived?: boolean;
+}
+interface ContactInput {
+  readonly id?: string;
+  readonly userId?: string;
+  readonly name?: string;
+  readonly email?: string;
+  readonly phone?: string;
+  readonly avatarUrl?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** The contact's id on a channel, such as a WhatsApp number. */
+  readonly identity?: {
+    readonly channel: string;
+    readonly externalId: string;
+  };
+}
+interface MessageInput {
+  readonly body: string;
+  /** `note` is an internal note only staff see. */
+  readonly kind?: "message" | "note";
+  readonly format?: "text" | "markdown";
+  readonly attachments?: readonly MessageAttachment[];
+  /** User ids; those who cannot read the inbox are dropped. */
+  readonly mentions?: readonly string[];
+  readonly replyTo?: string;
+  readonly externalId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** For the service: who writes. Defaults to `bot`. */
+  readonly authorType?: "contact" | "bot" | "system";
+  /** For the service: the caller posts to the channel itself, so no outbound job is queued. */
+  readonly deliveredByCaller?: boolean;
+}
+interface StartConversationInput {
+  /**
+   * A contact id or the fields to find or create one. Leave it out on a
+   * widget inbox to open the conversation as the signed-in visitor, staff
+   * included.
+   */
+  readonly contact?: string | ContactInput;
+  readonly subject?: string;
+  readonly priority?: ConversationPriority;
+  readonly botMode?: BotMode;
+  /** The Chat SDK thread id. Defaults to `inbox:<conversation id>`. */
+  readonly threadId?: string;
+  readonly assigneeId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly message?: string | MessageInput;
+}
+interface InboundInput {
+  readonly inboxId: string;
+  readonly threadId: string;
+  readonly contact: ContactInput & {
+    /** Shorthand for `identity` on the inbox's channel. */
+    readonly externalId?: string;
+  };
+  readonly message: Omit<MessageInput, "kind" | "authorType">;
+  readonly subject?: string;
+  /** `outbound` records a message sent from the platform by someone else. */
+  readonly direction?: "inbound" | "outbound";
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface ConversationFilter extends CursorPageOptions<Pick<Conversation, "id" | "lastMessageAt">> {
+  readonly inboxId?: string;
+  /** Defaults to `open`. */
+  readonly status?: ConversationStatus | "all";
+  readonly assignee?: "me" | "unassigned" | (string & {});
+  readonly teamId?: string;
+  readonly contactId?: string;
+  readonly search?: string;
+  /** The last item of the previous page. */
+  readonly cursor?: Pick<Conversation, "id" | "lastMessageAt">;
+  /** Up to 200. Defaults to 50. */
+  readonly limit?: number;
+}
+interface TemplateInput {
+  readonly name: string;
+  readonly channel: string;
+  readonly body: string;
+  readonly language?: string;
+  readonly inboxId?: string;
+  readonly variables?: readonly string[];
+  readonly externalId?: string;
+}
+/** The `inbox` SQL module as typed calls. */
+/** Hooks for `Inbox`: the top-level methods, and each group's under its name. */
+type InboxHooks = BlockHooks<Inbox> & {
+  readonly inboxes?: BlockHooks<Inbox["inboxes"]>;
+  readonly contacts?: BlockHooks<Inbox["contacts"]>;
+  readonly conversations?: BlockHooks<Inbox["conversations"]>;
+  readonly messages?: BlockHooks<Inbox["messages"]>;
+  readonly deliveries?: BlockHooks<Inbox["deliveries"]>;
+  readonly templates?: BlockHooks<Inbox["templates"]>;
+  readonly inbound?: BlockHooks<Inbox["inbound"]>;
+};
+interface Inbox {
+  readonly inboxes: {
+    create(input: CreateInboxInput): AsyncResult<InboxRow>;
+    update(id: string, patch: InboxPatch): AsyncResult<InboxRow>;
+    /** `null` removes the member. */
+    setMember(inboxId: string, userId: string, role: "agent" | "lead" | null): AsyncResult<boolean>;
+    createTeam(tenant: string, name: string): AsyncResult<{
+      readonly id: string;
+      readonly name: string;
+    }>;
+    setTeamMember(teamId: string, userId: string, present?: boolean): AsyncResult<boolean>;
+  };
+  readonly contacts: {
+    /** Finds the contact by id, identity, user or email, filling in what is missing. */
+    upsert(tenant: string, input: ContactInput): AsyncResult<Contact>;
+  };
+  readonly conversations: {
+    open(inboxId: string, input?: StartConversationInput): AsyncResult<Conversation>;
+    list(tenant: string | null, filter?: ConversationFilter): AsyncResult<readonly Conversation[]>;
+    get(conversationId: string): AsyncResult<Conversation | null>;
+    assign(conversationId: string, to: {
+      readonly assigneeId: string | null;
+      readonly teamId?: string | null;
+    }): AsyncResult<Conversation>;
+    setStatus(conversationId: string, status: ConversationStatus, options?: {
+      readonly snoozedUntil?: Temporal.Instant;
+    }): AsyncResult<Conversation>;
+    snooze(conversationId: string, until: Temporal.Instant): AsyncResult<Conversation>;
+    resolve(conversationId: string): AsyncResult<Conversation>;
+    reopen(conversationId: string): AsyncResult<Conversation>;
+    /** Hands a bot conversation to staff (`bot_mode = 'human'`) and tells them. */
+    handoff(conversationId: string, reason?: string): AsyncResult<Conversation>;
+    setBotMode(conversationId: string, mode: BotMode, reason?: string): AsyncResult<Conversation>;
+    markRead(conversationId: string): AsyncResult<Temporal.Instant>;
+    /** A typing ping on `inbox:<id>`; the service names the bot in `actor`. */
+    typing(conversationId: string, typing?: boolean, actor?: string): AsyncResult<boolean>;
+    events(conversationId: string): AsyncResult<readonly ConversationEvent[]>;
+    counts(tenant: string): AsyncResult<InboxCounts>;
+  };
+  readonly messages: {
+    send(conversationId: string, input: MessageInput): AsyncResult<InboxMessage>;
+    /** An internal note only staff see. */
+    note(conversationId: string, body: string, input?: Pick<MessageInput, "mentions" | "attachments" | "format">): AsyncResult<InboxMessage>;
+    list(conversationId: string, options?: CursorPageOptions<Temporal.Instant>): AsyncResult<readonly InboxMessage[]>;
+    get(messageId: string): AsyncResult<InboxMessage | null>;
+    edit(messageId: string, body: string): AsyncResult<InboxMessage>;
+    /** Leaves a tombstone with an empty body. */
+    remove(messageId: string): AsyncResult<InboxMessage>;
+    react(messageId: string, emoji: string, options?: {
+      readonly present?: boolean;
+      readonly actor?: string;
+    }): AsyncResult<Readonly<Record<string, readonly string[]>>>;
+  };
+  readonly deliveries: {
+    /** Service only: after posting a message on its channel. */
+    record(input: {
+      readonly messageId: string;
+      readonly channel: string;
+      readonly externalId?: string;
+      readonly status?: DeliveryStatus;
+      readonly error?: string;
+    }): AsyncResult<void>;
+    /** Service only: a status callback; returns how many deliveries moved. */
+    setStatus(input: {
+      readonly channel: string;
+      readonly externalId: string;
+      readonly status: DeliveryStatus;
+      readonly error?: string;
+    }): AsyncResult<number>;
+  };
+  readonly templates: {
+    upsert(tenant: string, input: TemplateInput): AsyncResult<MessageTemplate>;
+    delete(id: string): AsyncResult<boolean>;
+  };
+  /** Service only: channel messages, the webhook store and its sweeps. */
+  readonly inbound: {
+    /** A message that arrived on a channel: finds or opens the thread's conversation. */
+    record(input: InboundInput): AsyncResult<InboundResult>;
+    store(input: {
+      readonly adapter: string;
+      readonly body: string;
+      readonly externalId?: string;
+      readonly headers?: Readonly<Record<string, string>>;
+      readonly inboxId?: string;
+      readonly tenant?: string;
+    }): AsyncResult<{
+      readonly id: string;
+      readonly duplicate: boolean;
+    }>;
+    setStatus(id: string, status: "processing" | "processed" | "ignored" | "failed", error?: string): AsyncResult<boolean>;
+    pending(options?: {
+      readonly limit?: number;
+      readonly maxAttempts?: number;
+    }): AsyncResult<readonly StoredInboundEvent[]>;
+    purge(options?: {
+      readonly olderThan?: number | string;
+      readonly batch?: number;
+    }): AsyncResult<number>;
+  };
+  /** Service only: reopens snoozed conversations whose time came. */
+  wakeSnoozed(): AsyncResult<number>;
+  /**
+   * Erases a contact and its conversations for a data subject request
+   * (`inbox.manage` or the service). Remove the returned attachment paths
+   * from Storage afterwards.
+   */
+  purgeContact(contactId: string): AsyncResult<PurgedContact>;
+}
+/**
+ * The `inbox` SQL module as typed calls: inboxes, contacts, conversations,
+ * messages and notes, assignment, bot hand-off, read state, deliveries and
+ * the stored webhook events. The database checks every permission.
+ */
+declare function createInbox(options: InboxOptions): Inbox;
+//#endregion
+export { MessageTemplate as A, InboxCounts as C, MessageDelivery as D, MessageAttachment as E, StoredInboundEvent as M, MessageDirection as O, InboxChannel as S, InboxRow as T, ConversationEvent as _, Inbox as a, DeliveryStatus as b, InboxPatch as c, TemplateInput as d, createInbox as f, Conversation as g, Contact as h, InboundInput as i, PurgedContact as j, MessageKind as k, MessageInput as l, BotMode as m, ConversationFilter as n, InboxHooks as o, AuthorType as p, CreateInboxInput as r, InboxOptions as s, ContactInput as t, StartConversationInput as u, ConversationPriority as v, InboxMessage as w, InboundResult as x, ConversationStatus as y };