zupost 0.1.1 → 0.5.1

package/dist/index.d.ts

@@ -1,8 +1,28 @@
 import { Options } from '@react-email/render';
 import { ReactNode } from 'react';
 
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * @internal
+ * Internal HTTP client for the Zupost API. Not part of the public API surface.
+ */
+declare class HttpClient {
+    #private;
+    constructor(apiKey: string, baseUrl: string, userAgent: string);
+    request<T = unknown>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body: unknown): Promise<T>;
+    delete<T = unknown>(path: string, body?: unknown): Promise<T>;
+}
+
 /**
  * Options for sending an email.
+ *
+ * Zupost is template first: the recommended way to send is by providing a
+ * `templateId` (managed in the Zupost dashboard) together with `variables`.
+ * `html`, `markdown`, and `react` are supported as fallbacks for ad-hoc or
+ * dynamically generated content. Exactly one content source is required.
  */
 interface SendEmailOptions {
     /**
@@ -33,23 +53,28 @@ interface SendEmailOptions {
      */
     bcc?: string | string[];
     /**
-     * ID of the email template to use.
+     * ID of the email template to use. Preferred way of sending: content and
+     * subject are managed in the Zupost dashboard and can be changed without a
+     * deploy. Combine with `variables` for interpolation.
      */
     templateId?: string;
     /**
-     * Variables for template interpolation.
+     * Variables for template interpolation. Used together with `templateId`.
      */
     variables?: Record<string, string>;
     /**
-     * Markdown content for the email.
+     * Markdown content for the email. Fallback to `templateId` — use for ad-hoc
+     * or dynamically generated content.
      */
     markdown?: string;
     /**
-     * HTML content for the email.
+     * HTML content for the email. Fallback to `templateId` — use for ad-hoc or
+     * dynamically generated content.
      */
     html?: string;
     /**
-     * React component for the email.
+     * React component for the email. Fallback to `templateId` — use for ad-hoc
+     * or dynamically generated content rendered via React Email.
      */
     react?: ReactNode;
     /**
@@ -99,36 +124,40 @@ interface SendEmailResponse {
  * Emails API for sending transactional emails.
  */
 declare class Emails {
-    private readonly zupost;
-    constructor(zupost: Zupost);
+    private readonly http;
+    constructor(http: HttpClient);
     /**
-     * Send an email using template, markdown or HTML content.
+     * Send an email.
+     *
+     * Zupost is template first: prefer sending by `templateId` with `variables`
+     * so your content lives in the Zupost dashboard and can be edited without a
+     * deploy. Inline `html`, `markdown`, or `react` content is supported as a
+     * fallback for ad-hoc or dynamically generated emails.
      *
      * @param options - Email options including recipient, sender, and content.
-     * @returns A promise that resolves to the email response containing emailId.
+     * @returns A promise that resolves to the email response containing the email id.
      *
      * @example
      * ```typescript
      * const zupost = new Zupost('your-api-key');
      *
-     * // Send with HTML content
-     * const { emailId } = await zupost.emails.send({
+     * // Recommended: send with a template
+     * const { id } = await zupost.emails.send({
      *   from: 'sender@example.com',
      *   to: 'recipient@example.com',
-     *   subject: 'Hello World',
-     *   html: '<h1>Hello!</h1>',
+     *   templateId: 'welcome-template',
+     *   variables: { name: 'John' },
      * });
      *
-     * // Send with a template
+     * // Fallback: inline HTML
      * await zupost.emails.send({
      *   from: 'sender@example.com',
-     *   to: ['user1@example.com', 'user2@example.com'],
-     *   subject: 'Welcome!',
-     *   templateId: 'welcome-template',
-     *   variables: { name: 'John' },
+     *   to: 'recipient@example.com',
+     *   subject: 'Hello World',
+     *   html: '<h1>Hello!</h1>',
      * });
      *
-     * // Send with markdown
+     * // Fallback: inline markdown
      * await zupost.emails.send({
      *   from: 'sender@example.com',
      *   to: 'recipient@example.com',
@@ -168,8 +197,8 @@ interface SendCampaignResponse {
  * Campaigns API for sending email campaigns to audiences.
  */
 declare class Campaigns {
-    private readonly zupost;
-    constructor(zupost: Zupost);
+    private readonly http;
+    constructor(http: HttpClient);
     /**
      * Send a campaign to selected audiences.
      *
@@ -192,6 +221,403 @@ declare class Campaigns {
     send(options: SendCampaignOptions): Promise<SendCampaignResponse>;
 }
 
+type ContactEventType = 'CONTACT_CREATED' | 'CONTACT_UPDATED' | 'EMAIL_SENT' | 'EMAIL_DELIVERED' | 'EMAIL_OPENED' | 'EMAIL_CLICKED' | 'EMAIL_BOUNCED' | 'EMAIL_COMPLAINED' | 'EMAIL_FAILED' | 'SUBSCRIBED' | 'UNSUBSCRIBED' | 'MARKETING_CONSENT_GIVEN' | 'MARKETING_CONSENT_WITHDRAWN' | 'TRACKING_CONSENT_GIVEN' | 'TRACKING_CONSENT_WITHDRAWN' | 'REPLY_RECEIVED' | 'SEQUENCE_ENTERED' | 'SEQUENCE_EXITED' | 'SEQUENCE_STEP_COMPLETED' | 'TAG_ADDED' | 'TAG_REMOVED' | 'FORGOTTEN';
+type EmailRecipientType = 'TO' | 'CC' | 'BCC';
+interface ContactTag {
+    name: string;
+    createdAt: string;
+}
+interface Contact {
+    id: string;
+    email: string;
+    name: string | null;
+    firstSeenAt: string;
+    firstSeenSource: string;
+    metadata?: unknown;
+    marketingConsent: boolean;
+    marketingConsentAt?: string | null;
+    marketingConsentSource?: string | null;
+    trackingConsent: boolean;
+    trackingConsentAt?: string | null;
+    birthday?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    tags: ContactTag[];
+}
+interface ContactEvent {
+    id: string;
+    type: ContactEventType;
+    payload?: unknown;
+    emailId?: string | null;
+    sequenceRunId?: string | null;
+    source: string;
+    createdAt: string;
+}
+interface CreateContactOptions {
+    email: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    marketingConsent?: boolean;
+    marketingConsentSource?: string;
+    trackingConsent?: boolean;
+    tags?: string[];
+}
+interface UpdateContactOptions {
+    name?: string | null;
+    metadata?: Record<string, unknown> | null;
+    birthday?: string | null;
+    marketingConsent?: boolean;
+    marketingConsentSource?: string | null;
+    trackingConsent?: boolean;
+}
+interface ListContactsOptions {
+    skip?: number;
+    take?: number;
+    search?: string;
+    marketingConsent?: boolean;
+    tag?: string;
+}
+interface ListContactsResponse {
+    items: Contact[];
+    total: number;
+    skip: number;
+    take: number;
+}
+interface ListEventsOptions {
+    skip?: number;
+    take?: number;
+    type?: ContactEventType | ContactEventType[];
+}
+interface ListEventsResponse {
+    items: ContactEvent[];
+    total: number;
+    skip: number;
+    take: number;
+}
+interface ContactExport {
+    contact: Contact;
+    subscriptions: Array<{
+        id: string;
+        status: string;
+        source: string;
+        createdAt: string;
+        unsubscribedAt: string | null;
+        audiences: Array<{
+            id: string;
+            name: string;
+        }>;
+    }>;
+    tags: ContactTag[];
+    emails: Array<{
+        emailId: string;
+        subject: string | null;
+        from: string;
+        usageType: 'TRANSACTIONAL' | 'MARKETING';
+        latestStatus: string;
+        recipientType: EmailRecipientType;
+        sentAt: string;
+    }>;
+    timeline: ContactEvent[];
+    exportedAt: string;
+}
+interface ForgetContactResponse {
+    id: string;
+    forgottenAt: string;
+}
+
+/**
+ * Contacts API.
+ *
+ * A Contact is every email address Zupost has ever seen, with a chronological
+ * event timeline, consent state (marketing and tracking), tags and GDPR
+ * primitives (data export, right to be forgotten).
+ *
+ * Marketing emails require `marketingConsent: true` and an audience membership
+ * (Subscriber). Transactional emails do not require consent and can be sent
+ * to any contact or even an ad-hoc address.
+ */
+declare class Contacts {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create or upsert a contact by email. Idempotent on (project, email).
+     *
+     * @example
+     * ```typescript
+     * const contact = await zupost.contacts.create({
+     *   email: 'user@example.com',
+     *   name: 'Jane Doe',
+     *   marketingConsent: true,
+     *   marketingConsentSource: 'signup-form',
+     *   tags: ['vip', 'beta'],
+     * });
+     * ```
+     */
+    create(options: CreateContactOptions): Promise<Contact>;
+    /**
+     * Get a contact by ID.
+     */
+    get(id: string): Promise<Contact>;
+    /**
+     * List contacts with optional search, consent and tag filters.
+     */
+    list(options?: ListContactsOptions): Promise<ListContactsResponse>;
+    /**
+     * Update a contact. Pass only the fields that should change.
+     *
+     * Toggling `marketingConsent` or `trackingConsent` automatically records
+     * a corresponding ContactEvent for the audit trail.
+     */
+    update(id: string, patch: UpdateContactOptions): Promise<Contact>;
+    /**
+     * GDPR right-to-be-forgotten. Anonymises the contact, sets `forgottenAt`
+     * and disables consent. Existing email events are anonymised in a
+     * follow-up cascade.
+     */
+    forget(id: string): Promise<ForgetContactResponse>;
+    /**
+     * Get the chronological event timeline for a contact.
+     */
+    events(id: string, options?: ListEventsOptions): Promise<ListEventsResponse>;
+    /**
+     * GDPR data access export. Returns the complete record for a contact
+     * including all emails, events, subscriptions and tags.
+     */
+    export(id: string): Promise<ContactExport>;
+    /**
+     * Add a tag to a contact (idempotent).
+     */
+    addTag(id: string, name: string): Promise<ContactTag>;
+    /**
+     * Remove a tag from a contact.
+     */
+    removeTag(id: string, name: string): Promise<{
+        ok: true;
+    }>;
+}
+
+type SequenceType = 'TRANSACTIONAL' | 'MARKETING';
+type SequenceStatus = 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED';
+type SequenceTriggerType = 'MANUAL' | 'API' | 'AUDIENCE_SUBSCRIBE' | 'AUDIENCE_UNSUBSCRIBE' | 'TAG_ADDED' | 'TAG_REMOVED' | 'WEBHOOK' | 'SCHEDULED';
+type SequenceRunStatus = 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+type WaitDuration = {
+    minutes?: number;
+    hours?: number;
+    days?: number;
+};
+type BranchCondition = {
+    kind: 'has_tag';
+    tag: string;
+} | {
+    kind: 'opened_email';
+    sinceStepKey: string;
+} | {
+    kind: 'clicked_email';
+    sinceStepKey: string;
+} | {
+    kind: 'always';
+};
+type SequenceStep = {
+    key: string;
+    type: 'send_email';
+    name?: string;
+    config: {
+        templateId?: string;
+        subject?: string;
+        html?: string;
+        variables?: Record<string, unknown>;
+        fromHandle?: string;
+        fromDomainId?: string;
+    };
+    next?: string | null;
+} | {
+    key: string;
+    type: 'wait';
+    name?: string;
+    config: {
+        duration: WaitDuration;
+    };
+    next?: string | null;
+} | {
+    key: string;
+    type: 'branch';
+    name?: string;
+    config: {
+        condition: BranchCondition;
+    };
+    thenNext: string | null;
+    elseNext: string | null;
+} | {
+    key: string;
+    type: 'tag_add' | 'tag_remove';
+    name?: string;
+    config: {
+        tag: string;
+    };
+    next?: string | null;
+} | {
+    key: string;
+    type: 'update_contact';
+    name?: string;
+    config: {
+        fields: Record<string, unknown>;
+    };
+    next?: string | null;
+} | {
+    key: string;
+    type: 'webhook';
+    name?: string;
+    config: {
+        url: string;
+        method?: 'GET' | 'POST';
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    next?: string | null;
+} | {
+    key: string;
+    type: 'end';
+    name?: string;
+};
+type SequenceDefinition = {
+    entry: string;
+    steps: Record<string, SequenceStep>;
+};
+interface SequenceVersion {
+    id: string;
+    version: number;
+    definition: SequenceDefinition;
+    createdBy?: string | null;
+    createdAt: string;
+    activatedAt?: string | null;
+}
+interface Sequence {
+    id: string;
+    name: string;
+    description?: string | null;
+    type: SequenceType;
+    status: SequenceStatus;
+    triggerType: SequenceTriggerType;
+    triggerConfig?: unknown;
+    activeVersionId?: string | null;
+    activeVersion?: SequenceVersion | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SequenceRun {
+    id: string;
+    sequenceId: string;
+    sequenceVersionId: string;
+    contactId?: string | null;
+    adHocRecipient?: string | null;
+    payload?: unknown;
+    status: SequenceRunStatus;
+    currentStepKey?: string | null;
+    nextStepAt?: string | null;
+    enteredAt: string;
+    completedAt?: string | null;
+    error?: string | null;
+}
+interface CreateSequenceOptions {
+    name: string;
+    description?: string;
+    type?: SequenceType;
+    triggerType?: SequenceTriggerType;
+    triggerConfig?: unknown;
+    definition?: SequenceDefinition;
+}
+interface ListSequencesOptions {
+    skip?: number;
+    take?: number;
+    type?: SequenceType;
+    status?: SequenceStatus;
+    search?: string;
+}
+interface ListSequencesResponse {
+    items: Sequence[];
+    total: number;
+    skip: number;
+    take: number;
+}
+interface SaveVersionOptions {
+    definition: SequenceDefinition;
+    activate?: boolean;
+}
+interface TriggerRunOptions {
+    contactId?: string;
+    email?: string;
+    payload?: unknown;
+}
+interface ListRunsOptions {
+    skip?: number;
+    take?: number;
+    status?: SequenceRunStatus;
+    contactId?: string;
+}
+interface ListRunsResponse {
+    items: SequenceRun[];
+    total: number;
+    skip: number;
+    take: number;
+}
+
+/**
+ * Sequences API.
+ *
+ * A Sequence is a multi-step email journey. There are two kinds:
+ *
+ *   - MARKETING: requires marketing consent on the recipient and an
+ *     unsubscribe link in every send. Triggers off audience subscribe,
+ *     tags, etc.
+ *   - TRANSACTIONAL: no consent required, no unsubscribe link. Triggers
+ *     off API events, webhooks or schedules.
+ *
+ * Define a sequence in code with the `defineSequence` helper, then
+ * `client.sequences.saveVersion` to push it.
+ */
+declare class Sequences {
+    private readonly http;
+    constructor(http: HttpClient);
+    readonly runs: {
+        list: (sequenceId: string, options?: ListRunsOptions) => Promise<ListRunsResponse>;
+    };
+    /**
+     * Create a new sequence (always starts in DRAFT). Pass `definition` to
+     * seed the first version, or omit it to create an empty placeholder you
+     * can later push versions into.
+     */
+    create(options: CreateSequenceOptions): Promise<Sequence>;
+    /**
+     * Get a sequence by ID.
+     */
+    get(id: string): Promise<Sequence>;
+    /**
+     * List sequences with filters.
+     */
+    list(options?: ListSequencesOptions): Promise<ListSequencesResponse>;
+    /**
+     * Delete a sequence and all its versions and runs.
+     */
+    delete(id: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Change the lifecycle status: DRAFT, ACTIVE, PAUSED, ARCHIVED.
+     */
+    setStatus(id: string, status: SequenceStatus): Promise<Sequence>;
+    /**
+     * Save a new immutable version of the sequence definition. If `activate`
+     * is true (default), the new version becomes the active one for future
+     * triggered runs. Existing in-flight runs keep their pinned version.
+     */
+    saveVersion(id: string, options: SaveVersionOptions): Promise<SequenceVersion>;
+    /**
+     * Trigger a sequence run for a contact or ad-hoc email. The sequence
+     * must be ACTIVE.
+     */
+    trigger(id: string, options: TriggerRunOptions): Promise<SequenceRun>;
+}
+
 interface ZupostOptions {
     /**
      * Custom API URL. Defaults to 'https://api.zupost.com'.
@@ -199,8 +625,7 @@ interface ZupostOptions {
     baseUrl?: string;
 }
 declare class Zupost {
-    private readonly headers;
-    private readonly baseUrl;
+    #private;
     /**
      * Emails API for sending transactional emails.
      */
@@ -209,22 +634,83 @@ declare class Zupost {
      * Campaigns API for sending email campaigns to audiences.
      */
     readonly campaigns: Campaigns;
-    constructor(apiKey: string, options?: ZupostOptions);
-    /**
-     * @internal
-     * Makes a request to the Zupost API.
-     */
-    request<T = unknown>(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
     /**
-     * @internal
-     * Makes a GET request to the Zupost API.
+     * Contacts API. A Contact is every email address Zupost has ever seen,
+     * with a chronological event timeline, consent state and GDPR primitives.
      */
-    get<T = unknown>(path: string): Promise<T>;
+    readonly contacts: Contacts;
     /**
-     * @internal
-     * Makes a POST request to the Zupost API.
+     * Sequences API. A Sequence is a multi-step email journey (marketing or
+     * transactional) with branches, waits, tags and webhooks.
      */
-    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    readonly sequences: Sequences;
+    constructor(apiKey: string, options?: ZupostOptions);
 }
 
-export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, type ZupostOptions };
+/**
+ * Error thrown when the Zupost API returns a non-2xx response.
+ */
+declare class ZupostError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly requestId?: string;
+    readonly code?: string;
+    constructor(args: {
+        message: string;
+        status: number;
+        statusText: string;
+        body: string;
+        requestId?: string;
+        code?: string;
+    });
+    /** @internal */
+    static fromResponse(response: Response): Promise<ZupostError>;
+}
+
+/**
+ * Type-safe helper for defining a SequenceDefinition in code.
+ *
+ * Catches missing entry steps and unreachable next-pointers at compile time
+ * (via the explicit literal types) and at runtime (via the assertion below).
+ *
+ * @example
+ * ```typescript
+ * const onboarding = defineSequence({
+ *   entry: 'welcome',
+ *   steps: {
+ *     welcome: {
+ *       key: 'welcome',
+ *       type: 'send_email',
+ *       config: { templateId: 'welcome-mail' },
+ *       next: 'wait_3d',
+ *     },
+ *     wait_3d: {
+ *       key: 'wait_3d',
+ *       type: 'wait',
+ *       config: { duration: { days: 3 } },
+ *       next: 'tips',
+ *     },
+ *     tips: {
+ *       key: 'tips',
+ *       type: 'send_email',
+ *       config: { templateId: 'tips-mail' },
+ *       next: 'end',
+ *     },
+ *     end: { key: 'end', type: 'end' },
+ *   },
+ * });
+ *
+ * await zupost.sequences.create({
+ *   name: 'Onboarding',
+ *   type: 'MARKETING',
+ *   definition: onboarding,
+ * });
+ * ```
+ */
+declare function defineSequence<TSteps extends Record<string, SequenceStep>>(definition: {
+    entry: keyof TSteps & string;
+    steps: TSteps;
+}): SequenceDefinition;
+
+export { type BranchCondition, type Contact, type ContactEvent, type ContactEventType, type ContactExport, type ContactTag, type CreateContactOptions, type CreateSequenceOptions, type EmailRecipientType, type ForgetContactResponse, type ListContactsOptions, type ListContactsResponse, type ListEventsOptions, type ListEventsResponse, type ListRunsOptions, type ListRunsResponse, type ListSequencesOptions, type ListSequencesResponse, type SaveVersionOptions, type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, type Sequence, type SequenceDefinition, type SequenceRun, type SequenceRunStatus, type SequenceStatus, type SequenceStep, type SequenceTriggerType, type SequenceType, type SequenceVersion, type TriggerRunOptions, type UpdateContactOptions, type WaitDuration, Zupost, ZupostError, type ZupostOptions, defineSequence };