zupost 0.2.0 → 0.6.0

package/dist/index.d.ts

@@ -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,580 @@ 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>;
+}
+
+/**
+ * Verification status shared by a domain and its individual DNS records.
+ */
+type DomainVerificationStatus = 'NOT_STARTED' | 'PENDING' | 'SUCCESS' | 'FAILED' | 'TEMPORARY_FAILURE';
+type DomainDnsRecordType = 'MX' | 'TXT' | 'CNAME';
+/**
+ * A single DNS record you need to add at your DNS provider for the domain to
+ * verify (DKIM, SPF, the verification TXT record, optional DMARC, …).
+ */
+interface DomainDnsRecord {
+    type: DomainDnsRecordType;
+    /** Record name/host, e.g. `mail` or `@`. */
+    name: string;
+    /** Record value, e.g. the SPF or DKIM string. */
+    value: string;
+    /** Recommended TTL, e.g. `Auto`. */
+    ttl: string;
+    /** Priority for MX records. */
+    priority?: string | null;
+    /** Verification status of this specific record. */
+    status?: DomainVerificationStatus | null;
+    /** Whether adding this record is recommended (e.g. DMARC). */
+    recommended?: boolean;
+}
+/**
+ * A sending domain with its DNS records and verification state.
+ */
+interface Domain {
+    id: string;
+    /** The domain name, e.g. `example.com`. */
+    name: string;
+    projectId: string;
+    /** Primary sending region, e.g. `eu-central-1`. */
+    mainRegion: string;
+    /** All regions the domain is provisioned in. */
+    regions: string[];
+    clickTracking: boolean;
+    openTracking: boolean;
+    dkimTokens: string[];
+    dkimStatus?: DomainVerificationStatus | null;
+    /** Overall verification status of the domain. */
+    status?: DomainVerificationStatus | null;
+    spfStatus?: DomainVerificationStatus | null;
+    createdAt: string;
+    updatedAt: string;
+    dmarcAdded: boolean;
+    verificationInProcess: boolean;
+    errorMessage?: string | null;
+    subdomain?: string | null;
+    verificationError?: string | null;
+    lastCheckedTime?: string | null;
+    scheduledForDeletion: boolean;
+    /** DNS records to add at your DNS provider to verify the domain. */
+    dnsRecords: DomainDnsRecord[];
+}
+interface CreateDomainOptions {
+    /** The domain name to register, e.g. `example.com`. */
+    name: string;
+    /**
+     * Sending region for the domain. Defaults to `eu-central-1`.
+     */
+    region?: string;
+}
+interface DeleteDomainResponse {
+    success: boolean;
+    message: string;
+}
+interface VerifyDomainResponse {
+    message: string;
+}
+
+/**
+ * Domains API.
+ *
+ * A Domain is a sending domain you own (e.g. `example.com`). After creating it
+ * you add the returned `dnsRecords` (DKIM, SPF, verification TXT) at your DNS
+ * provider and then `verify` it. Only verified domains can send email and
+ * receive inbound mail.
+ */
+declare class Domains {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Register a new sending domain. The response contains the `dnsRecords` you
+     * need to add at your DNS provider before calling {@link verify}.
+     *
+     * @example
+     * ```typescript
+     * const domain = await zupost.domains.create({ name: 'example.com' });
+     * for (const record of domain.dnsRecords) {
+     *   console.log(record.type, record.name, record.value);
+     * }
+     * ```
+     */
+    create(options: CreateDomainOptions): Promise<Domain>;
+    /**
+     * Get a domain by ID, including its current verification status and DNS
+     * records.
+     */
+    get(id: string): Promise<Domain>;
+    /**
+     * List all domains in the project.
+     */
+    list(): Promise<Domain[]>;
+    /**
+     * Start the verification process for a domain. Add the DNS records returned
+     * by {@link create} or {@link get} first; Zupost then checks them and
+     * updates the domain's `status`.
+     */
+    verify(id: string): Promise<VerifyDomainResponse>;
+    /**
+     * Schedule a domain for deletion.
+     */
+    delete(id: string): Promise<DeleteDomainResponse>;
+}
+
+interface CreateInboundChannelOptions {
+    /** Human-readable name for the channel (1-100 characters). */
+    name: string;
+    /** ID of a verified domain that should receive inbound email. */
+    domainId: string;
+    /**
+     * HTTPS URL parsed inbound emails are delivered to. Must resolve to a
+     * public address.
+     */
+    webhookUrl: string;
+    /**
+     * Shared secret (32-512 characters) used to sign webhook deliveries so you
+     * can verify they originate from Zupost.
+     */
+    webhookSecret: string;
+}
+/**
+ * An inbound email channel: it routes mail received on a domain to your
+ * `webhookUrl`.
+ */
+interface InboundChannel {
+    id: string;
+    name: string;
+    projectId: string;
+    domainId: string;
+    webhookUrl: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Inbound API.
+ *
+ * Receive email sent to a verified domain by routing it through an inbound
+ * channel to your own HTTPS webhook. Deliveries are signed with the
+ * `webhookSecret` you provide so you can verify their authenticity.
+ */
+declare class Inbound {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Inbound channels route mail received on a domain to a webhook.
+     */
+    readonly channels: {
+        /**
+         * Create an inbound channel for a verified domain.
+         *
+         * @example
+         * ```typescript
+         * const channel = await zupost.inbound.channels.create({
+         *   name: 'Support inbox',
+         *   domainId: 'dom_123',
+         *   webhookUrl: 'https://example.com/zupost/inbound',
+         *   webhookSecret: process.env.ZUPOST_INBOUND_SECRET!,
+         * });
+         * ```
+         */
+        create: (options: CreateInboundChannelOptions) => Promise<InboundChannel>;
+    };
+}
+
 interface ZupostOptions {
     /**
      * Custom API URL. Defaults to 'https://api.zupost.com'.
@@ -235,6 +811,26 @@ 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;
+    /**
+     * Domains API. A Domain is a sending domain you own, with DNS records and
+     * verification state. Only verified domains can send and receive email.
+     */
+    readonly domains: Domains;
+    /**
+     * Inbound API. Receive email on a verified domain and have it delivered to
+     * your own webhook through an inbound channel.
+     */
+    readonly inbound: Inbound;
     constructor(apiKey: string, options?: ZupostOptions);
 }
 
@@ -259,4 +855,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 CreateDomainOptions, type CreateInboundChannelOptions, type CreateSequenceOptions, type DeleteDomainResponse, type Domain, type DomainDnsRecord, type DomainDnsRecordType, type DomainVerificationStatus, type EmailRecipientType, type ForgetContactResponse, type InboundChannel, 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 VerifyDomainResponse, type WaitDuration, Zupost, ZupostError, type ZupostOptions, defineSequence };