bitelio 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,328 @@
+interface BitelioOptions {
+    /**
+     * Your project's public key (`pk_…`), needed ONLY by `events.track`.
+     *
+     * That endpoint authenticates with the public key rather than the secret one — it is the same
+     * endpoint browsers and mobile apps post to, and it has no secret-key equivalent that takes an
+     * email address. Nothing is lost by supplying it here: a public key is not a secret, it ships in
+     * every page of your site.
+     */
+    publicKey?: string;
+    /** Defaults to `https://api.bitelio.com`. Point it at your own deployment if self-hosted. */
+    baseUrl?: string;
+    /** Per attempt, not for the whole call. Default 30s. */
+    timeoutMs?: number;
+    /** Retries AFTER the first attempt, on 429 and 5xx only. Default 2. */
+    maxRetries?: number;
+    /** Swap in a stub in tests, or a proxying fetch in production. */
+    fetch?: typeof globalThis.fetch;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    idempotencyKey?: string;
+    /** Overrides the bearer token for this call. Used by `events.track`, which needs the public key. */
+    authToken?: string;
+}
+/**
+ * The transport. Everything a resource does goes through `request`, so the retry policy, the
+ * timeout and the error shape are decided in exactly one place.
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    readonly publicKey: string | undefined;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(apiKey: string, options?: BitelioOptions);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** A key per call, so the retry above is safe by default rather than by remembering. */
+    static newIdempotencyKey(): string;
+}
+
+/** Whether a send actually went out. A test key records everything and delivers nothing. */
+type EmailMode = 'live' | 'test';
+type EmailStatus = 'PENDING' | 'SENDING' | 'HELD' | 'SENT' | 'DELIVERED' | 'RECEIVED' | 'OPENED' | 'CLICKED' | 'BOUNCED' | 'COMPLAINED' | 'FAILED';
+/** A send, as it appears in a listing. The rendered body is on `emails.get` only. */
+interface Email {
+    id: string;
+    to: string;
+    subject: string;
+    from: string;
+    fromName: string | null;
+    status: EmailStatus;
+    testMode: boolean;
+    /** The provider's id. Prefixed `test-` for a send that never left. */
+    messageId: string | null;
+    error: string | null;
+    opens: number;
+    clicks: number;
+    createdAt: string;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    openedAt: string | null;
+    clickedAt: string | null;
+    bouncedAt: string | null;
+    complainedAt: string | null;
+}
+/** One send, with the HTML that actually went out. */
+interface EmailDetail extends Email {
+    body: string;
+    replyTo: string | null;
+    toName: string | null;
+    headers: Record<string, string> | null;
+    sourceType: string;
+}
+interface EmailListParams {
+    limit?: number;
+    /** The previous page's `nextCursor`, verbatim. Opaque. */
+    cursor?: string;
+    /** `live` unless you say otherwise — a test send is noise a day later. */
+    mode?: 'live' | 'test' | 'all';
+    status?: EmailStatus;
+    /** Recipient address. Empty page if they are not a contact of your project. */
+    to?: string;
+    since?: Date | string;
+    until?: Date | string;
+}
+interface Page<T> {
+    data: T[];
+    /** `null` on the last page. */
+    nextCursor: string | null;
+}
+type Recipient = string | {
+    name?: string;
+    email: string;
+};
+interface SendParams {
+    to: Recipient | Recipient[];
+    subject?: string;
+    body?: string;
+    /** A template id, instead of `subject` + `body`. */
+    template?: string;
+    from?: string | {
+        name?: string;
+        email: string;
+    };
+    name?: string;
+    reply?: string;
+    headers?: Record<string, string>;
+    data?: Record<string, unknown>;
+    subscribed?: boolean;
+    attachments?: {
+        filename: string;
+        content: string;
+        contentType: string;
+    }[];
+    /**
+     * Overrides the key generated for you. Supply your own when the natural unit of work is not one
+     * call — the same order confirmation retried across two processes, say.
+     */
+    idempotencyKey?: string;
+}
+interface SendResult {
+    emails: {
+        contact: {
+            id: string;
+            email: string;
+        };
+        email: string;
+    }[];
+    timestamp: string;
+}
+interface Contact {
+    id: string;
+    email: string;
+    subscribed: boolean;
+    data: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TrackParams {
+    event: string;
+    email: string;
+    data?: Record<string, unknown>;
+    subscribed?: boolean;
+}
+
+interface CreateContactParams {
+    email: string;
+    subscribed?: boolean;
+    data?: Record<string, unknown>;
+}
+interface UpdateContactParams {
+    email?: string;
+    subscribed?: boolean;
+    data?: Record<string, unknown>;
+}
+declare class Contacts {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateContactParams): Promise<Contact>;
+    get(id: string): Promise<Contact>;
+    update(id: string, params: UpdateContactParams): Promise<Contact>;
+    /** Irreversible, and it takes the contact's send history with it. */
+    delete(id: string): Promise<void>;
+}
+
+declare class Emails {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Sends one transactional email, or one per recipient when `to` is an array.
+     *
+     * An idempotency key is generated for you unless you supply one. That is not a nicety: this
+     * client retries 429s and 5xx responses, and a retried send without a key is a duplicate in
+     * somebody's inbox.
+     */
+    send(params: SendParams): Promise<SendResult>;
+    /**
+     * One page of your send history, newest first.
+     *
+     * Shows live sends only unless you pass `mode`. Page by handing `nextCursor` straight back —
+     * it is opaque, and `null` means you have reached the end.
+     */
+    list(params?: EmailListParams): Promise<Page<Email>>;
+    /**
+     * One email, including the HTML that actually went out — after variables were substituted,
+     * blocks resolved and your brand applied. Most "the email looks wrong" reports end here.
+     */
+    get(id: string): Promise<EmailDetail>;
+    /**
+     * Every send matching the filter, one page at a time.
+     *
+     * An async iterator rather than an array: a project's history does not fit in memory, and the
+     * shape of this method is what stops somebody discovering that in production.
+     */
+    iterate(params?: Omit<EmailListParams, 'cursor'>): AsyncGenerator<Email>;
+}
+
+interface TrackResult {
+    contact: string;
+    event: string;
+    timestamp: string;
+}
+declare class Events {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Records an event against a contact, creating them if they are new. This is what triggers a
+     * workflow, so it is the call a SaaS makes from its own lifecycle code.
+     *
+     * Values in `data` are saved onto the contact and are available to every later message. To pass
+     * something for this event only, wrap it: `{orderId: {value: '123', persistent: false}}`.
+     *
+     * Authenticates with your PUBLIC key, which is why the client has to be given one. This endpoint
+     * is the same one browsers post to, and today it has no secret-key equivalent that identifies a
+     * contact by email address — `POST /events/track` does exist for secret keys, but it requires a
+     * contact id you would have to go and look up first. Supplying the public key is not a
+     * concession: it ships in every page of your own site already.
+     */
+    track(params: TrackParams): Promise<TrackResult>;
+}
+
+/**
+ * Verifying a webhook Bitelio sent you.
+ *
+ * The signature is HMAC-SHA256 over `{timestamp}.{rawBody}`, sent as `Bitelio-Signature` beside
+ * `Bitelio-Timestamp`. The timestamp is inside the signed string so a replayed old request can be
+ * rejected — the same scheme Stripe uses, which is deliberate: it is the one developers already
+ * know how to verify by hand.
+ */
+interface VerifyParams {
+    /**
+     * The RAW request body, as a string or Buffer — NOT a parsed object.
+     *
+     * This is the mistake everyone makes. `JSON.parse` then `JSON.stringify` reorders keys and
+     * changes whitespace, and the signature covers bytes. In Express, reach for
+     * `express.raw({type: 'application/json'})` on the webhook route.
+     */
+    payload: string | Buffer;
+    /** The `Bitelio-Signature` header, verbatim. */
+    signature: string;
+    /** The `Bitelio-Timestamp` header, verbatim. */
+    timestamp: string | number;
+    /** Your endpoint's signing secret. */
+    secret: string;
+    /**
+     * How old a request may be, in seconds. Default 300.
+     *
+     * This is what makes the timestamp worth signing: without a bound, a request captured once can
+     * be replayed for ever. Pass `Infinity` only if you have your own replay defence.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * True when the request really came from Bitelio and is recent enough.
+ *
+ * Accepts the request if ANY `v1=` part verifies. There is more than one during a secret
+ * rotation — the new secret and the still-live previous one — and a receiver mid-rollover that
+ * insisted on a single part would drop half its traffic.
+ */
+declare function verify(params: VerifyParams): boolean;
+/** `verify`, but it throws instead of returning false — handy at the top of a handler. */
+declare function assertValid(params: VerifyParams): void;
+
+type webhooks_VerifyParams = VerifyParams;
+declare const webhooks_assertValid: typeof assertValid;
+declare const webhooks_verify: typeof verify;
+declare namespace webhooks {
+  export { type webhooks_VerifyParams as VerifyParams, webhooks_assertValid as assertValid, webhooks_verify as verify };
+}
+
+/**
+ * Every failure this client throws.
+ *
+ * `requestId` is the field worth knowing about: it comes back on every response, and quoting it in
+ * a support conversation is the difference between "I get a 500" and something answerable.
+ */
+declare class BitelioError extends Error {
+    /** HTTP status. `0` when the request never reached the API — a DNS failure, a timeout. */
+    readonly status: number;
+    /** Machine-readable code, e.g. `VALIDATION_ERROR`. Absent on a transport failure. */
+    readonly code: string | undefined;
+    /** Quote this when reporting a problem. */
+    readonly requestId: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, init: {
+        status: number;
+        code?: string;
+        requestId?: string;
+        details?: Record<string, unknown>;
+    });
+    /** True for the failures a retry could plausibly fix. */
+    get retryable(): boolean;
+    static fromResponse(status: number, requestId: string | undefined, body: unknown): BitelioError;
+}
+
+/**
+ * The Bitelio client.
+ *
+ * ```ts
+ * import {Bitelio} from 'bitelio';
+ *
+ * const bitelio = new Bitelio(process.env.BITELIO_API_KEY!);
+ *
+ * await bitelio.emails.send({
+ *   from: 'onboarding@send.bitelio.com',
+ *   to: 'you@yourcompany.com',
+ *   subject: 'Hello',
+ *   body: '<p>It works.</p>',
+ * });
+ * ```
+ *
+ * Covers sending, reading your send history, contacts and events — what you drive from code.
+ * Campaigns, segments, templates and workflows are designed in the dashboard and are deliberately
+ * not here.
+ */
+declare class Bitelio {
+    readonly emails: Emails;
+    readonly contacts: Contacts;
+    readonly events: Events;
+    /** Verifying a webhook we sent you. Also exported standalone, for receivers with no client. */
+    static readonly webhooks: typeof webhooks;
+    constructor(apiKey: string, options?: BitelioOptions);
+}
+
+export { Bitelio, BitelioError, type BitelioOptions, type Contact, type CreateContactParams, type Email, type EmailDetail, type EmailListParams, type EmailMode, type EmailStatus, type Page, type Recipient, type SendParams, type SendResult, type TrackParams, type TrackResult, type UpdateContactParams, type VerifyParams, Bitelio as default, webhooks };

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+interface BitelioOptions {
+    /**
+     * Your project's public key (`pk_…`), needed ONLY by `events.track`.
+     *
+     * That endpoint authenticates with the public key rather than the secret one — it is the same
+     * endpoint browsers and mobile apps post to, and it has no secret-key equivalent that takes an
+     * email address. Nothing is lost by supplying it here: a public key is not a secret, it ships in
+     * every page of your site.
+     */
+    publicKey?: string;
+    /** Defaults to `https://api.bitelio.com`. Point it at your own deployment if self-hosted. */
+    baseUrl?: string;
+    /** Per attempt, not for the whole call. Default 30s. */
+    timeoutMs?: number;
+    /** Retries AFTER the first attempt, on 429 and 5xx only. Default 2. */
+    maxRetries?: number;
+    /** Swap in a stub in tests, or a proxying fetch in production. */
+    fetch?: typeof globalThis.fetch;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    idempotencyKey?: string;
+    /** Overrides the bearer token for this call. Used by `events.track`, which needs the public key. */
+    authToken?: string;
+}
+/**
+ * The transport. Everything a resource does goes through `request`, so the retry policy, the
+ * timeout and the error shape are decided in exactly one place.
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    readonly publicKey: string | undefined;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(apiKey: string, options?: BitelioOptions);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** A key per call, so the retry above is safe by default rather than by remembering. */
+    static newIdempotencyKey(): string;
+}
+
+/** Whether a send actually went out. A test key records everything and delivers nothing. */
+type EmailMode = 'live' | 'test';
+type EmailStatus = 'PENDING' | 'SENDING' | 'HELD' | 'SENT' | 'DELIVERED' | 'RECEIVED' | 'OPENED' | 'CLICKED' | 'BOUNCED' | 'COMPLAINED' | 'FAILED';
+/** A send, as it appears in a listing. The rendered body is on `emails.get` only. */
+interface Email {
+    id: string;
+    to: string;
+    subject: string;
+    from: string;
+    fromName: string | null;
+    status: EmailStatus;
+    testMode: boolean;
+    /** The provider's id. Prefixed `test-` for a send that never left. */
+    messageId: string | null;
+    error: string | null;
+    opens: number;
+    clicks: number;
+    createdAt: string;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    openedAt: string | null;
+    clickedAt: string | null;
+    bouncedAt: string | null;
+    complainedAt: string | null;
+}
+/** One send, with the HTML that actually went out. */
+interface EmailDetail extends Email {
+    body: string;
+    replyTo: string | null;
+    toName: string | null;
+    headers: Record<string, string> | null;
+    sourceType: string;
+}
+interface EmailListParams {
+    limit?: number;
+    /** The previous page's `nextCursor`, verbatim. Opaque. */
+    cursor?: string;
+    /** `live` unless you say otherwise — a test send is noise a day later. */
+    mode?: 'live' | 'test' | 'all';
+    status?: EmailStatus;
+    /** Recipient address. Empty page if they are not a contact of your project. */
+    to?: string;
+    since?: Date | string;
+    until?: Date | string;
+}
+interface Page<T> {
+    data: T[];
+    /** `null` on the last page. */
+    nextCursor: string | null;
+}
+type Recipient = string | {
+    name?: string;
+    email: string;
+};
+interface SendParams {
+    to: Recipient | Recipient[];
+    subject?: string;
+    body?: string;
+    /** A template id, instead of `subject` + `body`. */
+    template?: string;
+    from?: string | {
+        name?: string;
+        email: string;
+    };
+    name?: string;
+    reply?: string;
+    headers?: Record<string, string>;
+    data?: Record<string, unknown>;
+    subscribed?: boolean;
+    attachments?: {
+        filename: string;
+        content: string;
+        contentType: string;
+    }[];
+    /**
+     * Overrides the key generated for you. Supply your own when the natural unit of work is not one
+     * call — the same order confirmation retried across two processes, say.
+     */
+    idempotencyKey?: string;
+}
+interface SendResult {
+    emails: {
+        contact: {
+            id: string;
+            email: string;
+        };
+        email: string;
+    }[];
+    timestamp: string;
+}
+interface Contact {
+    id: string;
+    email: string;
+    subscribed: boolean;
+    data: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TrackParams {
+    event: string;
+    email: string;
+    data?: Record<string, unknown>;
+    subscribed?: boolean;
+}
+
+interface CreateContactParams {
+    email: string;
+    subscribed?: boolean;
+    data?: Record<string, unknown>;
+}
+interface UpdateContactParams {
+    email?: string;
+    subscribed?: boolean;
+    data?: Record<string, unknown>;
+}
+declare class Contacts {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateContactParams): Promise<Contact>;
+    get(id: string): Promise<Contact>;
+    update(id: string, params: UpdateContactParams): Promise<Contact>;
+    /** Irreversible, and it takes the contact's send history with it. */
+    delete(id: string): Promise<void>;
+}
+
+declare class Emails {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Sends one transactional email, or one per recipient when `to` is an array.
+     *
+     * An idempotency key is generated for you unless you supply one. That is not a nicety: this
+     * client retries 429s and 5xx responses, and a retried send without a key is a duplicate in
+     * somebody's inbox.
+     */
+    send(params: SendParams): Promise<SendResult>;
+    /**
+     * One page of your send history, newest first.
+     *
+     * Shows live sends only unless you pass `mode`. Page by handing `nextCursor` straight back —
+     * it is opaque, and `null` means you have reached the end.
+     */
+    list(params?: EmailListParams): Promise<Page<Email>>;
+    /**
+     * One email, including the HTML that actually went out — after variables were substituted,
+     * blocks resolved and your brand applied. Most "the email looks wrong" reports end here.
+     */
+    get(id: string): Promise<EmailDetail>;
+    /**
+     * Every send matching the filter, one page at a time.
+     *
+     * An async iterator rather than an array: a project's history does not fit in memory, and the
+     * shape of this method is what stops somebody discovering that in production.
+     */
+    iterate(params?: Omit<EmailListParams, 'cursor'>): AsyncGenerator<Email>;
+}
+
+interface TrackResult {
+    contact: string;
+    event: string;
+    timestamp: string;
+}
+declare class Events {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Records an event against a contact, creating them if they are new. This is what triggers a
+     * workflow, so it is the call a SaaS makes from its own lifecycle code.
+     *
+     * Values in `data` are saved onto the contact and are available to every later message. To pass
+     * something for this event only, wrap it: `{orderId: {value: '123', persistent: false}}`.
+     *
+     * Authenticates with your PUBLIC key, which is why the client has to be given one. This endpoint
+     * is the same one browsers post to, and today it has no secret-key equivalent that identifies a
+     * contact by email address — `POST /events/track` does exist for secret keys, but it requires a
+     * contact id you would have to go and look up first. Supplying the public key is not a
+     * concession: it ships in every page of your own site already.
+     */
+    track(params: TrackParams): Promise<TrackResult>;
+}
+
+/**
+ * Verifying a webhook Bitelio sent you.
+ *
+ * The signature is HMAC-SHA256 over `{timestamp}.{rawBody}`, sent as `Bitelio-Signature` beside
+ * `Bitelio-Timestamp`. The timestamp is inside the signed string so a replayed old request can be
+ * rejected — the same scheme Stripe uses, which is deliberate: it is the one developers already
+ * know how to verify by hand.
+ */
+interface VerifyParams {
+    /**
+     * The RAW request body, as a string or Buffer — NOT a parsed object.
+     *
+     * This is the mistake everyone makes. `JSON.parse` then `JSON.stringify` reorders keys and
+     * changes whitespace, and the signature covers bytes. In Express, reach for
+     * `express.raw({type: 'application/json'})` on the webhook route.
+     */
+    payload: string | Buffer;
+    /** The `Bitelio-Signature` header, verbatim. */
+    signature: string;
+    /** The `Bitelio-Timestamp` header, verbatim. */
+    timestamp: string | number;
+    /** Your endpoint's signing secret. */
+    secret: string;
+    /**
+     * How old a request may be, in seconds. Default 300.
+     *
+     * This is what makes the timestamp worth signing: without a bound, a request captured once can
+     * be replayed for ever. Pass `Infinity` only if you have your own replay defence.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * True when the request really came from Bitelio and is recent enough.
+ *
+ * Accepts the request if ANY `v1=` part verifies. There is more than one during a secret
+ * rotation — the new secret and the still-live previous one — and a receiver mid-rollover that
+ * insisted on a single part would drop half its traffic.
+ */
+declare function verify(params: VerifyParams): boolean;
+/** `verify`, but it throws instead of returning false — handy at the top of a handler. */
+declare function assertValid(params: VerifyParams): void;
+
+type webhooks_VerifyParams = VerifyParams;
+declare const webhooks_assertValid: typeof assertValid;
+declare const webhooks_verify: typeof verify;
+declare namespace webhooks {
+  export { type webhooks_VerifyParams as VerifyParams, webhooks_assertValid as assertValid, webhooks_verify as verify };
+}
+
+/**
+ * Every failure this client throws.
+ *
+ * `requestId` is the field worth knowing about: it comes back on every response, and quoting it in
+ * a support conversation is the difference between "I get a 500" and something answerable.
+ */
+declare class BitelioError extends Error {
+    /** HTTP status. `0` when the request never reached the API — a DNS failure, a timeout. */
+    readonly status: number;
+    /** Machine-readable code, e.g. `VALIDATION_ERROR`. Absent on a transport failure. */
+    readonly code: string | undefined;
+    /** Quote this when reporting a problem. */
+    readonly requestId: string | undefined;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, init: {
+        status: number;
+        code?: string;
+        requestId?: string;
+        details?: Record<string, unknown>;
+    });
+    /** True for the failures a retry could plausibly fix. */
+    get retryable(): boolean;
+    static fromResponse(status: number, requestId: string | undefined, body: unknown): BitelioError;
+}
+
+/**
+ * The Bitelio client.
+ *
+ * ```ts
+ * import {Bitelio} from 'bitelio';
+ *
+ * const bitelio = new Bitelio(process.env.BITELIO_API_KEY!);
+ *
+ * await bitelio.emails.send({
+ *   from: 'onboarding@send.bitelio.com',
+ *   to: 'you@yourcompany.com',
+ *   subject: 'Hello',
+ *   body: '<p>It works.</p>',
+ * });
+ * ```
+ *
+ * Covers sending, reading your send history, contacts and events — what you drive from code.
+ * Campaigns, segments, templates and workflows are designed in the dashboard and are deliberately
+ * not here.
+ */
+declare class Bitelio {
+    readonly emails: Emails;
+    readonly contacts: Contacts;
+    readonly events: Events;
+    /** Verifying a webhook we sent you. Also exported standalone, for receivers with no client. */
+    static readonly webhooks: typeof webhooks;
+    constructor(apiKey: string, options?: BitelioOptions);
+}
+
+export { Bitelio, BitelioError, type BitelioOptions, type Contact, type CreateContactParams, type Email, type EmailDetail, type EmailListParams, type EmailMode, type EmailStatus, type Page, type Recipient, type SendParams, type SendResult, type TrackParams, type TrackResult, type UpdateContactParams, type VerifyParams, Bitelio as default, webhooks };