@skrybe/sdk 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -1,52 +1,764 @@
-export interface SkrybeConfig {
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+interface TransportOptions {
     apiKey: string;
-    baseURL?: string;
+    baseUrl: string;
+    timeoutMs: number;
+    maxRetries: number;
+    fetch: FetchLike;
 }
-export interface SendEmailOptions {
+type Fields = Record<string, string | number | undefined>;
+interface RequestOptions {
+    /** Path relative to the install root, e.g. `api/lists/get-lists.php`. */
+    path: string;
+    /** Form fields. `api_key` is added automatically unless `anonymous`. */
+    body?: Fields;
+    /**
+     * `form` posts application/x-www-form-urlencoded, which is what every
+     * endpoint wants except api/emails/send-transactional.php, which reads
+     * php://input and needs a raw JSON body.
+     */
+    encoding?: 'form' | 'json';
+    method?: 'GET' | 'POST';
+    /** Skip the api_key: only api/stats/emails-sent.php is public. */
+    anonymous?: boolean;
+    /**
+     * Opt in to retrying this request. Off by default because most endpoints
+     * here create or send something, and none of them take an idempotency key:
+     * a 504 from a send that actually landed becomes a second campaign on
+     * retry. A dropped connection cannot be told apart from a response we never
+     * saw, so only reads set this.
+     */
+    retryable?: boolean;
+}
+declare class Transport {
+    private readonly opts;
+    constructor(opts: TransportOptions);
+    /**
+     * Perform a request and return the body as text.
+     *
+     * Legacy endpoints answer HTTP 200 with a prose error, so a 2xx here is not
+     * proof of success: recognised prose errors are thrown, and anything else is
+     * handed back for the caller to parse.
+     */
+    text(opts: RequestOptions): Promise<string>;
+    /** Perform a request against one of the endpoints that returns real JSON. */
+    json<T>(opts: RequestOptions): Promise<T>;
+    private send;
+}
+
+/** 0 off, 1 on, 2 anonymous. */
+type Tracking = 0 | 1 | 2;
+/** Opens, clicks, bounces and the rest, as campaign and autoresponder stats report them. */
+interface EngagementStats {
+    recipients: number;
+    /** `rate` is a percentage of delivered (recipients less hard bounces). */
+    opens: {
+        total: number;
+        unique: number;
+        rate: number;
+    };
+    /** `rate` is a percentage of recipients. */
+    clicks: {
+        total: number;
+        unique: number;
+        rate: number;
+    };
+    bounces: {
+        hard: number;
+        soft: number;
+    };
+    complaints: number;
+    unsubscribes: number;
+    links: {
+        url: string;
+        clicks: number;
+        unique_clicks: number;
+    }[];
+}
+
+/**
+ * `drip` sends each email a set time after someone joins; `annually` and
+ * `on_date` send on a Date custom field, every year or once.
+ */
+type AutoresponderType = 'drip' | 'annually' | 'on_date';
+interface Autoresponder {
+    id: number;
+    name: string;
+    /** `unknown` for a type this SDK predates. */
+    type: AutoresponderType | 'unknown';
+    /** Encrypted, like the ids `lists.list()` returns. */
+    list_id: string;
+    /** The date field an `annually` or `on_date` autoresponder sends on. */
+    custom_field: string | null;
+    emails: number;
+    enabled_emails: number;
+}
+interface AutoresponderEmail {
+    id: number;
+    autoresponder_id: number;
+    subject: string;
+    from_name: string;
+    from_email: string;
+    /** As stored: "immediately", "+3 days", "-1 days", or "" for the date itself. */
+    when: string;
+    enabled: boolean;
+    recipients: number;
+    /** Unix seconds. */
+    created_at: number | null;
+}
+interface AutoresponderWithEmails extends Autoresponder {
+    email_list: AutoresponderEmail[];
+}
+interface AutoresponderEmailStats extends EngagementStats {
+    id: number;
+    autoresponder_id: number;
+}
+interface CreateAutoresponderParams {
+    name: string;
+    type: AutoresponderType;
+    /** The encrypted list id. A list can have one drip autoresponder. */
+    listId: string;
+    /** Required for `annually` and `on_date`: a Date custom field of the list, one autoresponder per field. */
+    customField?: string;
+}
+interface CreateAutoresponderEmailParams {
+    subject: string;
+    htmlText: string;
+    plainText?: string;
+    preheader?: string;
+    /**
+     * When it goes. For a drip, "immediately" (the default) or a delay such as
+     * "+3 days"; for annually and on_date, "on" (the default, the date itself)
+     * or an offset such as "+9 hours" or "-1 days". Units: minute, hour, day,
+     * week, month.
+     */
+    when?: string;
+    /** Each falls back to the brand's sender. */
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string;
+    queryString?: string;
+    trackOpens?: Tracking;
+    trackClicks?: Tracking;
+    /** Emails are created off, as the dashboard creates them, unless this is true. */
+    enabled?: boolean;
+}
+declare class Autoresponders {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** The brand's autoresponders, or one list's. */
+    list(opts?: {
+        listId?: string;
+    }): Promise<Autoresponder[]>;
+    /** One autoresponder with its emails. */
+    get(autoresponderId: number): Promise<AutoresponderWithEmails>;
+    emailStats(emailId: number): Promise<AutoresponderEmailStats>;
+    /** Creates an autoresponder with no emails; add them with `createEmail()`. Not retried. */
+    create(params: CreateAutoresponderParams): Promise<Autoresponder>;
+    /** Adds an email to an autoresponder. Not retried: a repeat would add it twice. */
+    createEmail(autoresponderId: number, params: CreateAutoresponderEmailParams): Promise<AutoresponderEmail>;
+}
+
+interface CreateCampaignParams {
     fromName: string;
     fromEmail: string;
     replyTo: string;
+    title: string;
     subject: string;
     htmlText: string;
     plainText?: string;
-    to?: string[];
-    recipientVariables?: Record<string, Record<string, any>>;
+    /** Encrypted list ids. Needed, with `segmentIds`, only to send or schedule. */
     listIds?: string[];
+    segmentIds?: (string | number)[];
+    excludeListIds?: string[];
+    excludeSegmentIds?: (string | number)[];
     queryString?: string;
-    trackOpens?: 0 | 1 | 2;
-    trackClicks?: 0 | 1 | 2;
+    trackOpens?: Tracking;
+    trackClicks?: Tracking;
+    /** Send immediately once created. */
+    send?: boolean;
+    /** Schedule instead, e.g. "June 15, 2027 6:05pm". Minutes must be a multiple of 5. */
     scheduleDateTime?: string;
+    /** e.g. "America/New_York". Falls back to the brand's timezone. */
     scheduleTimezone?: string;
 }
-export interface CreateCampaignOptions {
+interface CreateCampaignResult {
+    outcome: 'created' | 'sending' | 'scheduled';
+    /**
+     * Only for a plain create: the sending and scheduling paths of create.php
+     * answer with bare prose and no id.
+     */
+    campaignId?: string;
+}
+/** As the brand's campaign list labels them. */
+declare const CAMPAIGN_STATUSES: readonly ["draft", "scheduled", "preparing", "sending", "sent", "paused"];
+type CampaignStatus = (typeof CAMPAIGN_STATUSES)[number];
+/** One row of `campaigns.list()`. */
+interface Campaign {
+    id: number;
+    title: string;
+    subject: string;
+    status: CampaignStatus;
+    from_name: string;
+    from_email: string;
+    reply_to: string;
+    recipients: number;
+    to_send: number;
+    /** Unix seconds. */
+    sent_at: number | null;
+    /** Unix seconds, only while scheduled. */
+    scheduled_at: number | null;
+    timezone: string | null;
+    /** `ui`, or `api` for campaigns created by `emails.send()`. */
+    source: string;
+}
+interface CampaignDetail extends Campaign {
+    preheader: string;
+    query_string: string;
+    track_opens: Tracking;
+    track_clicks: Tracking;
+    /** Encrypted, like the ids `lists.list()` returns. */
+    list_ids: string[];
+    exclude_list_ids: string[];
+    segment_ids: number[];
+    exclude_segment_ids: number[];
+    web_version: string;
+    /** Only with `includeContent`. */
+    html_text?: string;
+    plain_text?: string;
+}
+interface CampaignStats extends EngagementStats {
+    id: number;
+    status: CampaignStatus;
+}
+interface ListCampaignsParams {
+    /** 1-based. */
+    page?: number;
+    /** At most 100. */
+    limit?: number;
+    status?: CampaignStatus;
+}
+declare const MAX_CAMPAIGNS_PAGE = 100;
+interface Recipients {
+    /** Encrypted list ids. At least one list or segment is required. */
+    listIds?: string[];
+    segmentIds?: (string | number)[];
+    excludeListIds?: string[];
+    excludeSegmentIds?: (string | number)[];
+    /** Run every check and count the recipients, but send nothing. */
+    dryRun?: boolean;
+}
+interface SendCampaignResult {
+    status: 'sending' | 'dry_run';
+    campaign_id: number;
+    /** Unique active subscribers the campaign goes (or would go) to. */
+    recipients: number;
+}
+interface ScheduleCampaignParams extends Recipients {
+    /** Anything PHP's strtotime() reads, e.g. "2027-06-15 18:05" or "June 15, 2027 6:05pm". */
+    at: string;
+    /** e.g. "Africa/Lagos". Defaults to the account's timezone. */
+    timezone?: string;
+}
+interface ScheduleCampaignResult {
+    status: 'scheduled' | 'dry_run';
+    campaign_id: number;
+    recipients: number;
+    /** Unix seconds. */
+    scheduled_at: number;
+    timezone: string;
+}
+/** test-send.php refuses more than this many addresses per request. */
+declare const MAX_TEST_EMAILS = 5;
+interface TestSendResult {
+    campaign_id: number;
+    /** One per address, in the order sent. */
+    results: {
+        email: string;
+        ok: boolean;
+        error: string | null;
+    }[];
+}
+/** Fields `campaigns.update()` can change. Only those given change. */
+interface UpdateCampaignParams {
+    title?: string;
+    subject?: string;
+    preheader?: string;
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string;
+    htmlText?: string;
+    plainText?: string;
+    queryString?: string;
+    trackOpens?: Tracking;
+    trackClicks?: Tracking;
+}
+declare const ACTIVITY_TYPES: readonly ["opens", "clicks", "bounces", "complaints", "unsubscribes"];
+type ActivityType = (typeof ACTIVITY_TYPES)[number];
+/** One subscriber's part in a campaign. `opens`/`country` only for opens, `clicks`/`links` only for clicks. */
+interface CampaignActivity {
+    email: string;
+    name: string;
+    /** Encrypted, like the ids `lists.list()` returns. */
+    list_id: string;
+    opens?: number;
+    /** Where they first opened it, when known. */
+    country?: string | null;
+    clicks?: number;
+    links?: string[];
+}
+interface CampaignActivityPage {
+    campaign_id: number;
+    type: ActivityType;
+    page: number;
+    limit: number;
+    /** Subscribers across all pages. */
+    total: number;
+    activity: CampaignActivity[];
+}
+interface CampaignActivityParams {
+    type?: ActivityType;
+    page?: number;
+    /** At most 1000. */
+    limit?: number;
+}
+declare const MAX_ACTIVITY_PAGE = 1000;
+declare class Campaigns {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * `api/campaigns/create.php` creates a draft, and optionally sends or
+     * schedules it in the same call. To send a draft that already exists, see
+     * `send()`.
+     */
+    create(params: CreateCampaignParams): Promise<CreateCampaignResult>;
+    /** One page, newest first. An empty page is an empty array, not an error. */
+    list(params?: ListCampaignsParams): Promise<Campaign[]>;
+    /** Every page, fetched in order at the largest page size. */
+    listAll(params?: Omit<ListCampaignsParams, 'page' | 'limit'>): Promise<Campaign[]>;
+    get(campaignId: number, opts?: {
+        includeContent?: boolean;
+    }): Promise<CampaignDetail>;
+    stats(campaignId: number): Promise<CampaignStats>;
+    /**
+     * `api/campaigns/send.php` sends an existing draft. It only ever claims a
+     * draft, so a repeat after a lost response answers "Campaign has already been
+     * sent" rather than sending twice. It is still not retried: that answer
+     * would turn a success into a reported failure.
+     */
+    send(campaignId: number, recipients: Recipients): Promise<SendCampaignResult>;
+    /**
+     * Sends the campaign as a test to up to 5 addresses. Each request counts
+     * against a per-brand limit shared with the dashboard (20 an hour), so it is
+     * never retried.
+     */
+    testSend(campaignId: number, emails: string[]): Promise<TestSendResult>;
+    /**
+     * Schedules a draft, or moves a scheduled campaign. The recipients are
+     * reserved against the quota now and handed back by `unschedule()`.
+     */
+    schedule(campaignId: number, params: ScheduleCampaignParams): Promise<ScheduleCampaignResult>;
+    /** Back to a draft, with its quota reservation refunded. */
+    unschedule(campaignId: number): Promise<{
+        status: 'draft';
+        campaign_id: number;
+    }>;
+    /** Edits a draft or scheduled campaign and returns it as `get()` would. */
+    update(campaignId: number, changes: UpdateCampaignParams): Promise<CampaignDetail>;
+    /** A new draft copied from the campaign, in the same brand. */
+    duplicate(campaignId: number, opts?: {
+        title?: string;
+    }): Promise<CampaignDetail>;
+    /**
+     * Deletes the campaign with its links and attachments; a sent one loses its
+     * report. Refused while the campaign is preparing or sending.
+     */
+    delete(campaignId: number): Promise<{
+        campaign_id: number;
+        deleted: true;
+    }>;
+    /**
+     * A page of who opened, clicked, bounced, complained or unsubscribed. Opens
+     * and clicks are in the order subscribers first did them.
+     */
+    activity(campaignId: number, params?: CampaignActivityParams): Promise<CampaignActivityPage>;
+    /** Every page of one activity type, at the largest page size. */
+    activityAll(campaignId: number, type: ActivityType): Promise<CampaignActivity[]>;
+}
+
+/** send.php refuses more than this, and says so with a 400. */
+declare const MAX_RECIPIENTS = 250;
+interface SendEmailParams {
     fromName: string;
     fromEmail: string;
     replyTo: string;
-    title: string;
     subject: string;
     htmlText: string;
     plainText?: string;
-    listIds?: string;
-    segmentIds?: string;
-    excludeListIds?: string;
-    excludeSegmentIds?: string;
+    /** Addresses to send to, at most 250. Without `listIds` these are added to a new list. */
+    to?: string[];
+    /** Per-recipient values, referenced in the body as `[recipient.first]`. */
+    recipientVariables?: Record<string, Record<string, unknown>>;
+    /** Encrypted list ids, as `lists.list()` returns them. */
+    listIds?: string[];
     queryString?: string;
-    trackOpens?: 0 | 1 | 2;
-    trackClicks?: 0 | 1 | 2;
-    sendCampaign?: 0 | 1;
+    trackOpens?: Tracking;
+    trackClicks?: Tracking;
+    /** e.g. "June 15, 2027 6:05pm". */
     scheduleDateTime?: string;
+    /** e.g. "Africa/Lagos". Falls back to the brand's timezone. */
     scheduleTimezone?: string;
 }
-export interface List {
+interface SendEmailResult {
+    message: string;
+    /** The campaign the send created behind the scenes. */
+    campaignId?: string;
+}
+interface SendTransactionalParams {
+    toEmail: string;
+    subject: string;
+    /** At least one of `htmlBody` and `plainBody` is required. */
+    htmlBody?: string;
+    plainBody?: string;
+    /** Each falls back to the brand's configured value when omitted. */
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string;
+}
+interface SendTransactionalResult {
+    message: string;
+    messageId?: string;
+}
+declare class Emails {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * `api/emails/send.php`: a bulk send to addresses or lists. It creates a
+     * campaign behind the scenes; the subject doubles as its title.
+     */
+    send(params: SendEmailParams): Promise<SendEmailResult>;
+    /**
+     * `api/emails/send-transactional.php`: one email, delivered immediately with
+     * nothing queued. For OTPs, password resets and receipts.
+     */
+    sendTransactional(params: SendTransactionalParams): Promise<SendTransactionalResult>;
+}
+
+interface List {
+    /**
+     * An encrypted value, not the number in the dashboard URL. Pass it back as
+     * given wherever a list id is wanted.
+     */
+    id: string;
+    name: string;
+}
+type OptIn = 'single' | 'double';
+type CustomFieldType = 'text' | 'date';
+interface CustomField {
+    /** As used in personalization tags: `[Name,fallback=]`. */
+    name: string;
+    /** As the API stores it. */
+    type: 'Text' | 'Date';
+}
+/** One list from `get()`, `create()`, `update()` or the custom-field methods. */
+interface ListDetail extends List {
+    opt_in: OptIn;
+    /** `active` is who a campaign goes to: confirmed, and not unsubscribed, bounced or complained. */
+    subscribers: {
+        active: number;
+        unconfirmed: number;
+        unsubscribed: number;
+        bounced: number;
+        complained: number;
+    };
+    /** In the order subscribers' values are stored. */
+    custom_fields: CustomField[];
+}
+declare class Lists {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** The brand's lists. An empty brand is an empty array, not an error. */
+    list(opts?: {
+        includeHidden?: boolean;
+    }): Promise<List[]>;
+    get(listId: string): Promise<ListDetail>;
+    /** Not retried: a repeat after a lost response would create a second list. */
+    create(params: {
+        name: string;
+        optIn?: OptIn;
+    }): Promise<ListDetail>;
+    update(listId: string, changes: {
+        name?: string;
+        optIn?: OptIn;
+    }): Promise<ListDetail>;
+    /**
+     * Deletes the list with its subscribers, segments, autoresponders and rules.
+     * Refused while a scheduled or sending campaign is going to it.
+     */
+    delete(listId: string): Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    /**
+     * Subscribers a campaign to this list would reach.
+     *
+     * Anything but a bare integer is a failure and is thrown, never reported as
+     * 0: "this list is empty" is the one wrong answer a caller cannot detect.
+     */
+    activeSubscriberCount(listId: string): Promise<number>;
+    /** Adds a field; every subscriber gets an empty value for it. Returns the list with its fields. */
+    addCustomField(listId: string, params: {
+        name: string;
+        type?: CustomFieldType;
+    }): Promise<ListDetail>;
+    /**
+     * Renames a field, keeping subscribers' values. The autoresponders and
+     * segment conditions that use it follow; tags already in campaigns keep the
+     * old name.
+     */
+    renameCustomField(listId: string, name: string, newName: string): Promise<ListDetail>;
+    /** Deletes a field and every subscriber's value for it. Refused while an autoresponder or segment uses it. */
+    deleteCustomField(listId: string, name: string): Promise<ListDetail>;
+}
+
+interface Brand {
     id: string;
     name: string;
 }
-export declare class SkrybeSDK {
-    private client;
-    private apiKey;
-    constructor(config: SkrybeConfig);
-    private createFormData;
-    sendEmail(options: SendEmailOptions): Promise<string>;
-    createCampaign(options: CreateCampaignOptions): Promise<string>;
-    getLists(includeHidden?: boolean): Promise<List[]>;
+declare class Brands {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * The key's own brand: a brand key gets exactly one row. Empty, not an error,
+     * when there is none.
+     */
+    list(): Promise<Brand[]>;
+}
+declare class Stats {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Emails sent across the whole installation (campaigns, autoresponders and
+     * transactional), not a per-brand figure. Public and cached for 5 minutes.
+     */
+    totalEmailsSent(): Promise<number>;
+}
+
+interface SubscriberRef {
+    /** The encrypted list id, as `lists.list()` returns it. */
+    listId: string;
+    email: string;
+}
+interface SubscribeParams extends SubscriberRef {
+    name?: string;
+    /** Two-letter ISO 3166-1 code, e.g. NG. */
+    country?: string;
+    ipAddress?: string;
+    referrer?: string;
+    /** Record GDPR consent for an EU signup. */
+    gdpr?: boolean;
+    /** Add to a double opt-in list as single opt-in, skipping confirmation. */
+    silent?: boolean;
+    /**
+     * Custom fields, keyed by the name the list shows, e.g. `Birthday` for a
+     * field whose tag is `[Birthday,fallback=]`. Spaces are taken out before
+     * sending, as the server matches on.
+     */
+    fields?: Record<string, string>;
+}
+type SubscribeOutcome = 'subscribed' | 'already_subscribed';
+/** Every subscriber is in exactly one of these; `active` is who a campaign sends to. */
+declare const SUBSCRIBER_STATUSES: readonly ["active", "unconfirmed", "unsubscribed", "bounced", "complained"];
+type SubscriberStatus = (typeof SUBSCRIBER_STATUSES)[number];
+interface Subscriber {
+    email: string;
+    name: string;
+    status: SubscriberStatus;
+    /** Unix seconds. */
+    joined_at: number | null;
+    /** By field name, in the list's order. Dates are YYYY-MM-DD; empty values are null. */
+    custom_fields: Record<string, string | null>;
+}
+interface SubscribersPage {
+    list_id: string;
+    status: SubscriberStatus | null;
+    page: number;
+    limit: number;
+    /** Subscribers matching the status filter, across all pages. */
+    total: number;
+    subscribers: Subscriber[];
+}
+interface ListSubscribersParams {
+    status?: SubscriberStatus;
+    /** 1-based. */
+    page?: number;
+    /** At most 1000. */
+    limit?: number;
+}
+declare const MAX_SUBSCRIBERS_PAGE = 1000;
+declare class Subscribers {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Adds an address to a list. Posting one that is already there updates its
+     * name and custom fields, and resolves `already_subscribed` rather than
+     * throwing, so re-running an import is safe.
+     */
+    subscribe(params: SubscribeParams): Promise<SubscribeOutcome>;
+    /** Marks the address unsubscribed from the list. */
+    unsubscribe(ref: SubscriberRef): Promise<void>;
+    /** Removes the subscriber outright, rather than marking it unsubscribed. */
+    delete(ref: SubscriberRef): Promise<void>;
+    /**
+     * One of Subscribed, Unsubscribed, Unconfirmed, Bounced, Soft bounced or
+     * Complained. Returned as given, so a status added server-side surfaces
+     * rather than being rejected.
+     */
+    status(ref: SubscriberRef): Promise<string>;
+    /** One page of a list's subscribers, oldest first. */
+    list(listId: string, params?: ListSubscribersParams): Promise<SubscribersPage>;
+    /**
+     * Every page, at the largest page size. Oldest first, so someone joining
+     * mid-way lands on a later page instead of shifting the ones already read.
+     */
+    listAll(listId: string, params?: {
+        status?: SubscriberStatus;
+    }): Promise<Subscriber[]>;
+}
+
+/** The editor the Skrybe dashboard opens a template in. */
+type TemplateEditor = 'html' | 'dragdrop';
+interface Template {
+    id: number;
+    name: string;
+    from_name: string;
+    from_email: string;
+    reply_to: string;
+    editor: TemplateEditor;
+    /** Only from `get()` with `includeContent`, and from create and update. */
+    html_text?: string;
+    plain_text?: string;
+}
+interface TemplateFields {
+    name?: string;
+    htmlText?: string;
+    plainText?: string;
+    fromName?: string;
+    fromEmail?: string;
+    replyTo?: string;
+    editor?: TemplateEditor;
+}
+declare class Templates {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** The brand's templates by name, without their HTML. */
+    list(): Promise<Template[]>;
+    get(templateId: number, opts?: {
+        includeContent?: boolean;
+    }): Promise<Template>;
+    /** Not retried: a repeat would create a second template. */
+    create(fields: TemplateFields & {
+        name: string;
+        htmlText: string;
+    }): Promise<Template>;
+    /** Only the fields given change. */
+    update(templateId: number, fields: TemplateFields): Promise<Template>;
+    /** Campaigns already made from it are unaffected. */
+    delete(templateId: number): Promise<{
+        template_id: number;
+        deleted: true;
+    }>;
+}
+
+declare const DEFAULT_BASE_URL = "https://dashboard.skry.be";
+interface SkrybeOptions {
+    /** A brand's API key, from Settings in the Skrybe dashboard. Keep it server-side. */
+    apiKey: string;
+    /** Defaults to https://dashboard.skry.be. */
+    baseUrl?: string;
+    /** Per attempt. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /**
+     * Extra attempts for reads after a dropped connection or a 429/502/503/504.
+     * Defaults to 2. Writes are never retried: the API has no idempotency keys,
+     * so a retried send could go out twice.
+     */
+    maxRetries?: number;
+    /**
+     * The fetch to use, defaulting to the global one. Pass your own to route
+     * through a proxy or trust a corporate CA, e.g. undici's fetch with a
+     * dispatcher. There is deliberately no option to skip TLS verification.
+     */
+    fetch?: FetchLike;
+}
+declare class Skrybe {
+    readonly emails: Emails;
+    readonly campaigns: Campaigns;
+    readonly lists: Lists;
+    readonly subscribers: Subscribers;
+    readonly templates: Templates;
+    readonly autoresponders: Autoresponders;
+    readonly brands: Brands;
+    readonly stats: Stats;
+    constructor(options: SkrybeOptions);
+}
+
+/**
+ * The Skrybe API answers most failures with HTTP 200 and a prose sentence.
+ * Only api/emails/send.php, api/emails/send-transactional.php and
+ * api/stats/emails-sent.php use real status codes.
+ *
+ * Everything here exists to turn that into something code can branch on: every
+ * failure is a `SkrybeError` with a stable `code`, and its subclass says what
+ * kind of failure it is.
+ */
+/**
+ * - `authentication`: the API key is missing or wrong.
+ * - `invalid_request`: the request itself is wrong; retrying it unchanged will fail again.
+ * - `rate_limit`: a quota or rate limit was hit.
+ * - `connection`: the API could not be reached, or did not answer in time.
+ * - `api`: anything else the API refused or got wrong.
+ */
+type SkrybeErrorType = 'authentication' | 'invalid_request' | 'rate_limit' | 'connection' | 'api';
+interface SkrybeErrorOptions {
+    /** What to do about it, when we know. */
+    hint?: string;
+    /** HTTP status of the response, when there was one. */
+    status?: number;
+    /** Raw response body, kept for debugging odd endpoints. */
+    raw?: string;
+    cause?: unknown;
+}
+declare class SkrybeError extends Error {
+    /** Stable machine-readable slug, e.g. `list_not_found`. */
+    readonly code: string;
+    readonly type: SkrybeErrorType;
+    readonly hint?: string;
+    readonly status?: number;
+    readonly raw?: string;
+    constructor(type: SkrybeErrorType, code: string, message: string, opts?: SkrybeErrorOptions);
+}
+declare class AuthenticationError extends SkrybeError {
+    constructor(code: string, message: string, opts?: SkrybeErrorOptions);
+}
+declare class InvalidRequestError extends SkrybeError {
+    constructor(code: string, message: string, opts?: SkrybeErrorOptions);
+}
+declare class RateLimitError extends SkrybeError {
+    constructor(code: string, message: string, opts?: SkrybeErrorOptions);
+}
+declare class ConnectionError extends SkrybeError {
+    constructor(code: string, message: string, opts?: SkrybeErrorOptions);
+}
+declare class ApiError extends SkrybeError {
+    constructor(code: string, message: string, opts?: SkrybeErrorOptions);
 }
+
+/**
+ * Sent in the User-Agent. A constant rather than read from package.json, which
+ * not every runtime can load; scripts/release.mjs keeps the two in step and a
+ * test fails if they drift.
+ */
+declare const VERSION = "2.0.0";
+
+export { ACTIVITY_TYPES, type ActivityType, ApiError, AuthenticationError, type Autoresponder, type AutoresponderEmail, type AutoresponderEmailStats, type AutoresponderType, type AutoresponderWithEmails, type Brand, CAMPAIGN_STATUSES, type Campaign, type CampaignActivity, type CampaignActivityPage, type CampaignActivityParams, type CampaignDetail, type CampaignStats, type CampaignStatus, ConnectionError, type CreateAutoresponderEmailParams, type CreateAutoresponderParams, type CreateCampaignParams, type CreateCampaignResult, type CustomField, type CustomFieldType, DEFAULT_BASE_URL, type EngagementStats, type FetchLike, InvalidRequestError, type List, type ListCampaignsParams, type ListDetail, type ListSubscribersParams, MAX_ACTIVITY_PAGE, MAX_CAMPAIGNS_PAGE, MAX_RECIPIENTS, MAX_SUBSCRIBERS_PAGE, MAX_TEST_EMAILS, type OptIn, RateLimitError, type Recipients, SUBSCRIBER_STATUSES, type ScheduleCampaignParams, type ScheduleCampaignResult, type SendCampaignResult, type SendEmailParams, type SendEmailResult, type SendTransactionalParams, type SendTransactionalResult, Skrybe, SkrybeError, type SkrybeErrorType, type SkrybeOptions, type SubscribeOutcome, type SubscribeParams, type Subscriber, type SubscriberRef, type SubscriberStatus, type SubscribersPage, type Template, type TemplateEditor, type TemplateFields, type TestSendResult, type Tracking, type UpdateCampaignParams, VERSION };