zupost 0.2.0 → 0.5.1

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { Options } from '@react-email/render';
 import { ReactNode } from 'react';
 
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /**
  * @internal
  * Internal HTTP client for the Zupost API. Not part of the public API surface.
@@ -12,6 +12,8 @@ declare class HttpClient {
     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>;
 }
 
 /**
@@ -219,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'.
@@ -235,6 +634,16 @@ declare class Zupost {
      * Campaigns API for sending email campaigns to audiences.
      */
     readonly campaigns: Campaigns;
+    /**
+     * Contacts API. A Contact is every email address Zupost has ever seen,
+     * with a chronological event timeline, consent state and GDPR primitives.
+     */
+    readonly contacts: Contacts;
+    /**
+     * Sequences API. A Sequence is a multi-step email journey (marketing or
+     * transactional) with branches, waits, tags and webhooks.
+     */
+    readonly sequences: Sequences;
     constructor(apiKey: string, options?: ZupostOptions);
 }
 
@@ -259,4 +668,49 @@ declare class ZupostError extends Error {
     static fromResponse(response: Response): Promise<ZupostError>;
 }
 
-export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, ZupostError, type ZupostOptions };
+/**
+ * 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 };