@sentroy-co/client-sdk 2.5.2 → 2.6.2

package/src/resources/webhooks.ts

@@ -0,0 +1,115 @@
+import type { HttpClient } from "../http"
+import type {
+  CreateWebhookParams,
+  UpdateWebhookParams,
+  Webhook,
+  WebhookDelivery,
+  WebhookDeliveryListParams,
+  WebhookDeliveryListResult,
+  WebhookDispatchResult,
+  WebhookTestParams,
+} from "../types"
+
+class WebhookDeliveries {
+  constructor(
+    private http: HttpClient,
+    private webhookId: string,
+  ) {}
+
+  /**
+   * List recorded test/replay dispatches for a webhook. Production
+   * deliveries (driven by the mail server) live elsewhere — this
+   * returns only what was fired from the Sentroy console or this SDK's
+   * `test` / `replay` calls.
+   */
+  async list(
+    params?: WebhookDeliveryListParams,
+  ): Promise<WebhookDeliveryListResult> {
+    const query: Record<string, unknown> = {}
+    if (params?.page !== undefined) query.page = params.page
+    if (params?.limit !== undefined) query.limit = params.limit
+    if (params?.status) query.status = params.status
+    return this.http.get<WebhookDeliveryListResult>(
+      `/webhooks/${encodeURIComponent(this.webhookId)}/deliveries`,
+      query,
+    )
+  }
+
+  /** Get a single delivery row, including the full payload + response body. */
+  async get(deliveryId: string): Promise<WebhookDelivery> {
+    return this.http.get<WebhookDelivery>(
+      `/webhooks/${encodeURIComponent(this.webhookId)}/deliveries/${encodeURIComponent(deliveryId)}`,
+    )
+  }
+
+  /**
+   * Re-fire the recorded payload at the webhook's *current* URL. The
+   * new row is linked to this one via `replayOf`.
+   */
+  async replay(deliveryId: string): Promise<WebhookDispatchResult> {
+    return this.http.post<WebhookDispatchResult>(
+      `/webhooks/${encodeURIComponent(this.webhookId)}/deliveries/${encodeURIComponent(deliveryId)}/replay`,
+    )
+  }
+}
+
+export class Webhooks {
+  constructor(private http: HttpClient) {}
+
+  /** List webhooks across the company, or scoped to a single domain. */
+  async list(domainId?: string): Promise<Webhook[]> {
+    return this.http.get<Webhook[]>(
+      "/webhooks",
+      domainId ? { domainId } : undefined,
+    )
+  }
+
+  /** Get a single webhook by id. */
+  async get(id: string): Promise<Webhook> {
+    return this.http.get<Webhook>(`/webhooks/${encodeURIComponent(id)}`)
+  }
+
+  /**
+   * Register a webhook for one or more events on a domain. The response
+   * includes a `secret` — store it now; subsequent reads only return the
+   * webhook config without the secret.
+   */
+  async create(params: CreateWebhookParams): Promise<Webhook> {
+    return this.http.post<Webhook>("/webhooks", params)
+  }
+
+  /** Patch URL, event list, or `active` flag. */
+  async update(id: string, params: UpdateWebhookParams): Promise<Webhook> {
+    return this.http.patch<Webhook>(
+      `/webhooks/${encodeURIComponent(id)}`,
+      params,
+    )
+  }
+
+  /** Delete a webhook. In-flight deliveries are not retried. */
+  async delete(id: string): Promise<void> {
+    await this.http.del<{ message: string }>(
+      `/webhooks/${encodeURIComponent(id)}`,
+    )
+  }
+
+  /**
+   * Manually fire a custom event payload at a webhook's current URL.
+   * Returns the dispatch result (status, duration, deliveryId) and
+   * records a row in the delivery log.
+   */
+  async test(
+    id: string,
+    params: WebhookTestParams,
+  ): Promise<WebhookDispatchResult> {
+    return this.http.post<WebhookDispatchResult>(
+      `/webhooks/${encodeURIComponent(id)}/test`,
+      params,
+    )
+  }
+
+  /** Delivery-log scope for a single webhook id. */
+  deliveries(webhookId: string): WebhookDeliveries {
+    return new WebhookDeliveries(this.http, webhookId)
+  }
+}

package/src/types.ts

@@ -322,3 +322,219 @@ export interface StorageUsage {
   buckets: StorageUsageBucket[]
   byType: StorageUsageByType[]
 }
+
+// ── Audience / Contacts ───────────────────────────────────────────────────
+
+export type ContactStatus = "active" | "unsubscribed" | "bounced"
+
+export interface Contact {
+  id: string
+  companyId: string
+  email: string
+  name?: string
+  tags: string[]
+  status: ContactStatus
+  metadata: Record<string, unknown>
+  lastEmailedAt?: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface ContactList {
+  id: string
+  companyId: string
+  name: string
+  description?: string
+  memberCount?: number
+  createdAt: string
+  updatedAt: string
+}
+
+export interface CreateContactParams {
+  email: string
+  name?: string
+  tags?: string[]
+  metadata?: Record<string, unknown>
+}
+
+export interface UpdateContactParams {
+  email?: string
+  name?: string
+  tags?: string[]
+  status?: ContactStatus
+  metadata?: Record<string, unknown>
+}
+
+export interface ContactListParams {
+  page?: number
+  limit?: number
+  status?: ContactStatus
+  /** Comma-joined when sent over the wire — pass an array, the SDK joins. */
+  tags?: string[]
+}
+
+export interface ContactListResult {
+  contacts: Contact[]
+  total: number
+  page: number
+  limit: number
+}
+
+export interface CreateAudienceListParams {
+  name: string
+  description?: string
+}
+
+// ── Suppressions ──────────────────────────────────────────────────────────
+
+export interface Suppression {
+  id: string
+  email: string
+  reason: string
+  domainId: string
+  createdAt: string
+  domain?: { domain: string }
+}
+
+export interface AddSuppressionParams {
+  email: string
+  /** Free-form label (e.g. "manual", "complaint"). Defaults backend-side. */
+  reason?: string
+  domainId: string
+}
+
+export interface SuppressionListParams {
+  page?: number
+  limit?: number
+  domainId?: string
+  reason?: string
+}
+
+// ── Webhooks ──────────────────────────────────────────────────────────────
+
+export type WebhookEvent =
+  | "sent"
+  | "bounced"
+  | "failed"
+  | "opened"
+  | "clicked"
+  | "unsubscribed"
+
+export interface Webhook {
+  id: string
+  url: string
+  events: string[]
+  active: boolean
+  domainId: string
+  /** Returned only on create — used to verify HMAC signatures of deliveries. */
+  secret?: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface CreateWebhookParams {
+  url: string
+  events: WebhookEvent[] | string[]
+  domainId: string
+}
+
+export interface UpdateWebhookParams {
+  url?: string
+  events?: WebhookEvent[] | string[]
+  active?: boolean
+}
+
+// ── Webhook deliveries ────────────────────────────────────────────────────
+
+export type WebhookDeliveryStatus = "success" | "failed" | "pending"
+
+export type WebhookDeliveryKind = "test" | "replay"
+
+export interface WebhookDelivery {
+  id: string
+  webhookId: string
+  companyId: string
+  kind: WebhookDeliveryKind
+  event: string
+  payload: Record<string, unknown>
+  /** URL the dispatcher actually POSTed to (frozen at dispatch time). */
+  url: string
+  /** HTTP status returned by the receiver — 0 if the request never landed. */
+  responseStatus: number
+  /** Truncated response body (max 4 KB). */
+  responseBody: string
+  durationMs: number
+  status: WebhookDeliveryStatus
+  error?: string
+  /** Set when this row is a replay of an earlier delivery. */
+  replayOf?: string
+  /** User id, email, or "system" for token/internal callers. */
+  triggeredBy: string
+  createdAt: string
+}
+
+export interface WebhookDeliveryListParams {
+  page?: number
+  limit?: number
+  status?: WebhookDeliveryStatus
+}
+
+export interface WebhookDeliveryListResult {
+  items: WebhookDelivery[]
+  total: number
+  page: number
+  limit: number
+}
+
+export interface WebhookTestParams {
+  event: WebhookEvent | string
+  payload: Record<string, unknown>
+}
+
+export interface WebhookDispatchResult {
+  deliveryId: string
+  responseStatus: number
+  durationMs: number
+  status: "success" | "failed"
+  error?: string
+}
+
+// ── Logs ──────────────────────────────────────────────────────────────────
+
+export type MailLogStatus =
+  | "queued"
+  | "processing"
+  | "sent"
+  | "bounced"
+  | "failed"
+
+export interface MailLog {
+  id: string
+  to: string
+  from: string
+  subject: string
+  status: MailLogStatus
+  messageId: string | null
+  domainId: string
+  domain?: { domain: string }
+  templateId: string | null
+  variables: Record<string, unknown> | null
+  scheduledAt?: string | null
+  sentAt: string | null
+  bouncedAt: string | null
+  openedAt?: string | null
+  clickedAt?: string | null
+  error: string | null
+  createdAt: string
+}
+
+export interface LogListParams {
+  page?: number
+  limit?: number
+  status?: MailLogStatus
+  domainId?: string
+  /** ISO timestamp lower bound (inclusive). */
+  from?: string
+  /** ISO timestamp upper bound (inclusive). */
+  to?: string
+}