@agentisend/sdk-node 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,499 @@
+/**
+ * Wire types, snake_case, mirroring what the API returns.
+ *
+ * Hand-written rather than imported from the server: a published client must
+ * not drag Fastify and Drizzle into a user's dependency tree. The guard against
+ * drift is the quickstart test, which runs this client against the real API.
+ */
+export type AddressList = string | string[];
+export interface Attachment {
+    filename?: string;
+    /** base64-encoded bytes. Provide this or `path`. */
+    content?: string;
+    /** Remote URL fetched at send time. Provide this or `content`. */
+    path?: string;
+    content_type?: string;
+    content_id?: string;
+}
+export interface SendEmailPayload {
+    from: string;
+    to: AddressList;
+    subject: string;
+    cc?: AddressList;
+    bcc?: AddressList;
+    reply_to?: AddressList;
+    html?: string;
+    text?: string;
+    headers?: Record<string, string>;
+    /** An object map, or Resend's `{name, value}[]` — both normalize to the map. */
+    tags?: Record<string, string> | {
+        name: string;
+        value: string;
+    }[];
+    /** ISO 8601, up to 30 days ahead. */
+    scheduled_at?: string;
+    attachments?: Attachment[];
+}
+export type MessageStatus = 'queued' | 'scheduled' | 'sent' | 'delivered' | 'delivery_delayed' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'failed' | 'canceled' | 'suppressed';
+export interface AttachmentView {
+    filename: string;
+    content_type: string | null;
+    content_id: string | null;
+    size_bytes: number | null;
+    path: string | null;
+}
+export interface Email {
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[] | null;
+    bcc: string[] | null;
+    reply_to: string[] | null;
+    subject: string;
+    html: string | null;
+    text: string | null;
+    headers: Record<string, string> | null;
+    tags: Record<string, string> | null;
+    attachments: AttachmentView[] | null;
+    scheduled_at: string | null;
+    status: MessageStatus;
+    last_event: MessageStatus | null;
+    provider_message_id: string | null;
+    api_key_id: string | null;
+    domain: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ListEmailsQuery {
+    status?: MessageStatus;
+    from?: string;
+    to?: string;
+    domain?: string;
+    api_key_id?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+    cursor?: string;
+    /** Resend's name for `cursor`; the API accepts either. */
+    after?: string;
+}
+/** Paging for every list endpoint: one envelope, one query shape (M5.2). */
+export interface ListQuery {
+    limit?: number;
+    cursor?: string;
+    /** Resend's name for `cursor`; the API accepts either. */
+    after?: string;
+}
+/** One component on the public status page, and what it reports about itself. */
+export interface ServiceComponent {
+    name: string;
+    state: 'operational' | 'degraded' | 'down' | 'unknown';
+    detail: string;
+}
+export interface ServiceStatus {
+    status: 'operational' | 'degraded' | 'outage';
+    time: string;
+    components: ServiceComponent[];
+}
+/** One API call this account made, as the request log recorded it (M5.9). */
+export interface RequestLogEntry {
+    id: string;
+    request_id: string;
+    method: string;
+    path: string;
+    /** The route template — what you group by when one id is not the question. */
+    route: string | null;
+    status: number;
+    duration_ms: number;
+    /** The catalogue code on a refusal; null when nothing refused. */
+    error_code: string | null;
+    api_key_id: string | null;
+    user_agent: string | null;
+    created_at: string;
+}
+/** One attachment on a message you sent (M5.10). Ids are stable positions. */
+export interface SentAttachment {
+    id: string;
+    filename: string;
+    content_type: string | null;
+    size_bytes: number | null;
+    content_id: string | null;
+    /** Set when you sent a URL instead of bytes — nothing was stored here. */
+    path: string | null;
+    /** False for a URL attachment, and once retention has taken the message. */
+    bytes_available: boolean;
+}
+/** One attachment on a received message (M5.8). Ids are stable positions. */
+export interface ReceivedAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    content_id: string | null;
+}
+/** A message someone sent to one of your domains. */
+export interface ReceivedEmail {
+    id: string;
+    from: string;
+    to: string;
+    subject: string | null;
+    received_at: string;
+    size_bytes: number;
+    attachment_count: number;
+    /** Present on the single read. Data as it arrived — this SDK renders nothing. */
+    headers?: Record<string, string>;
+    text?: string | null;
+    html?: string | null;
+    attachments?: ReceivedAttachment[];
+}
+/** The types a declared event field can take (M5.7). */
+export type EventFieldType = 'string' | 'number' | 'boolean' | 'date' | 'enum';
+/** What an account says one of its custom events looks like. */
+export interface EventDefinition {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Field name → declared type. Flat, because event payloads are flat. */
+    schema: Record<string, EventFieldType>;
+    /** When false, fields the schema does not declare are allowed through. */
+    strict: boolean;
+    last_seen_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** One step of one automation run, and what it did (M5.6). */
+export interface AutomationRunStep {
+    index: number;
+    kind: string;
+    /** `skipped` is a real outcome: a step that did nothing on purpose. */
+    status: 'succeeded' | 'skipped' | 'failed';
+    output: Record<string, unknown> | null;
+    error: string | null;
+    started_at: string;
+    finished_at: string | null;
+}
+/** One execution of one automation. `steps` is present on the single read. */
+export interface AutomationRun {
+    id: string;
+    automation_id: string;
+    version_number: number | null;
+    trigger_type: string;
+    event_name: string | null;
+    contact_id: string | null;
+    status: 'running' | 'succeeded' | 'failed';
+    started_at: string;
+    finished_at: string | null;
+    steps?: AutomationRunStep[];
+}
+/** One item's outcome in a suppression batch (M5.5). */
+export interface SuppressionBatchItem {
+    index: number;
+    email: string;
+    status: 'added' | 'removed' | 'not_found' | 'rejected';
+    id?: string;
+    error?: {
+        code: string;
+        message: string;
+        fix: string;
+        docs_url: string;
+    };
+}
+/** M5.4 — a subscription topic: the kind of mail a contact consented to. */
+export interface Topic {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Whether a contact who never answered receives this topic. */
+    default_subscribed: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/** One contact's standing on one topic, and what decided it. */
+export interface ContactTopic {
+    id: string;
+    name: string;
+    subscribed: boolean;
+    /** 'explicit' when the contact answered; 'default' when the topic did. */
+    basis: 'explicit' | 'default';
+    source: string | null;
+    updated_at: string | null;
+}
+export interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface BatchItemResult {
+    index: number;
+    status: 'accepted' | 'rejected';
+    id?: string;
+    error?: {
+        code: string;
+        message: string;
+        fix: string;
+        docs_url: string;
+        details?: {
+            path: string;
+            message: string;
+        }[];
+    };
+}
+export type ApiKeyPermission = 'full_access' | 'sending_access';
+export interface ApiKey {
+    id: string;
+    name: string;
+    permission: ApiKeyPermission;
+    domain_scope: string | null;
+    token_prefix: string;
+    created_at: string;
+    last_used_at: string | null;
+}
+export interface CreatedApiKey {
+    id: string;
+    /** Shown exactly once. */
+    token: string;
+}
+export type EventType = string;
+export interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: EventType[];
+    disabled: boolean;
+    /** True when deliveries also carry svix-id / -timestamp / -signature (M5.11). */
+    svix_compat: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreatedWebhookEndpoint extends WebhookEndpoint {
+    /** Shown exactly once. Store it — no endpoint returns it again. */
+    secret: string;
+}
+export interface DeadLetter {
+    id: string;
+    delivery_id: string | null;
+    event_id: string;
+    event_type: EventType;
+    occurred_at: string;
+    attempts: number;
+    last_status_code: number | null;
+    last_response_body: string | null;
+    reason: string;
+    payload: Record<string, unknown>;
+    created_at: string;
+}
+export interface ReplayResult {
+    replayed: number;
+    delivery_ids: string[];
+    truncated: boolean;
+}
+export type LimitPeriod = 'hourly' | 'daily' | 'monthly';
+export interface Limit {
+    api_key_id: string;
+    /** null = unlimited. */
+    budget_per_period: number | null;
+    period: LimitPeriod;
+    consumed_in_period: number;
+    period_started_at: string;
+    /** null = unlimited. */
+    rate_ceiling_per_minute: number | null;
+    consumed_in_window: number;
+    rate_window_started_at: string;
+    paused: boolean;
+    paused_at: string | null;
+    paused_reason: string | null;
+    updated_at: string;
+}
+export type TrustState = 'ok' | 'warning' | 'throttled' | 'paused';
+export interface TrustStanding {
+    state: TrustState;
+    reasons: string[];
+    next_review_at: string | null;
+    history: {
+        type: string;
+        reason: string | null;
+        occurred_at: string;
+    }[];
+}
+/** A tier someone can buy, or `none` — no plan in force. There is no free tier. */
+export type PlanTier = 'none' | 'starter' | 'pro' | 'scale';
+export type PaidTier = Exclude<PlanTier, 'none'>;
+export type PlanStatus = 'none' | 'trialing' | 'active' | 'past_due' | 'canceled';
+export type BillingTerm = 'month' | 'year';
+export interface BillingTermPrice {
+    per_month_minor: number;
+    total_minor: number;
+    months: number;
+    discount_percent: number;
+}
+/** GET /billing/plan — the plan an account runs under, in a shape an agent can budget against. */
+export interface BillingPlan {
+    /** The tier in force: `pro` during the 14-day trial, `none` without a plan. */
+    tier: PlanTier;
+    plan_status: PlanStatus;
+    /** True only for an owner or admin in the console whose account has no plan in force. Always false for an API key. */
+    needs_plan_selection: boolean;
+    billing_term: BillingTerm | null;
+    entitlements: {
+        tier: PlanTier;
+        included_emails_per_month: number;
+        retention_days: number;
+        max_domains: number | null;
+        max_seats: number;
+        overage_minor_per_1000_emails: number | null;
+    };
+    subscription: {
+        status: string;
+        price_lookup_key: string | null;
+        current_period_end: string | null;
+        cancel_at_period_end: boolean;
+    } | null;
+    billing_configured: boolean;
+    trial: {
+        eligible: boolean;
+        days: number;
+        started_at: string | null;
+        ends_at: string | null;
+        days_left: number | null;
+        emails_used: number | null;
+        email_cap: number;
+    };
+    /** The terms that can be bought right now. */
+    terms_on_sale: BillingTerm[];
+    plans: {
+        tier: PaidTier;
+        name: string;
+        featured: boolean;
+        trial_eligible: boolean;
+        included_emails_per_month: number;
+        max_domains: number | null;
+        max_seats: number;
+        retention_days: number;
+        prices: {
+            month: BillingTermPrice;
+            year: BillingTermPrice;
+        };
+    }[];
+    viewer: {
+        role: 'owner' | 'admin' | 'viewer' | null;
+        can_purchase: boolean;
+        can_start_trial: boolean;
+    };
+    purchasable: {
+        tier: PaidTier;
+        monthly_price_minor: number;
+        included_emails_per_month: number;
+    }[];
+}
+export type DomainRegion = 'us' | 'eu';
+/** One-release aliases the API still accepts on input. */
+export type LegacyDomainRegion = 'us-east-1' | 'eu-west-1' | 'sa-east-1' | 'ap-northeast-1';
+export interface DomainRecord {
+    record: 'SPF' | 'DKIM' | 'DMARC' | 'RETURN_PATH' | 'TRACKING' | 'TRACKING_CAA' | 'RECEIVING';
+    name: string;
+    type: 'TXT' | 'MX' | 'CNAME' | 'CAA';
+    value: string;
+    ttl: number;
+    priority: number | null;
+    /** `recommended` is DMARC and TrackingCAA's resting state: advised, never required. */
+    status: 'pending' | 'verified' | 'failed' | 'recommended';
+    checked_at: string | null;
+    /** What to do about this record, the alternative accepted forms included. */
+    fix: string;
+}
+export interface Domain {
+    id: string;
+    name: string;
+    region: DomainRegion;
+    status: 'pending' | 'verified' | 'failed' | 'partially_verified' | 'partially_failed';
+    dkim_selector: string;
+    /** A8 — both off unless turned on with `domains.update`. */
+    click_tracking: boolean;
+    open_tracking: boolean;
+    tracking_subdomain: string;
+    /**
+     * DNS sheet. Present on create, get, verify, and update. `list()` omits it
+     * (research/01-resend-api-baseline.md:182); call `get(id)` for the records.
+     */
+    records?: DomainRecord[];
+    /** Tracking records that are not yet verified. Detail only, never on list. */
+    tracking_issues?: {
+        record: 'TRACKING' | 'TRACKING_CAA';
+        message: string;
+        fix: string;
+    }[];
+    created_at: string;
+    verified_at: string | null;
+}
+export interface Deleted {
+    id: string;
+    deleted: boolean;
+}
+/** M4.8 — one person on an account, and what they may do. */
+export interface TeamMember {
+    id: string;
+    user_id: string;
+    email: string;
+    name: string | null;
+    role: 'owner' | 'admin' | 'viewer';
+    /** True for the member the credential is acting as. */
+    is_you: boolean;
+    created_at: string;
+}
+/** M4.8 — an invitation that has not been accepted, cancelled or expired. */
+export interface TeamInvite {
+    id: string;
+    email: string;
+    role: 'owner' | 'admin' | 'viewer';
+    invited_by: string | null;
+    invited_by_email: string | null;
+    expires_at: string;
+    created_at: string;
+}
+/** M4.9 — one change on the account, with what it looked like before. */
+export interface AuditEntry {
+    id: string;
+    account_id: string | null;
+    /** `user` when a person did it through the console, `api_key` for a key. */
+    actor_type: string;
+    actor_id: string | null;
+    actor_user_id: string | null;
+    actor_email: string | null;
+    action: string;
+    target_type: string | null;
+    target_id: string | null;
+    /** Shapes only: field names, counts and states — never message content. */
+    before: Record<string, unknown>;
+    after: Record<string, unknown>;
+    reason: string | null;
+    created_at: string;
+}
+/** M4.16 - one remediation step, ready to execute rather than to interpret. */
+export interface ExplainAction {
+    do: string;
+    call?: {
+        method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+        path: string;
+        body?: Record<string, unknown>;
+    };
+}
+/** What happened to a message, and what to do about it. */
+export interface ExplainReport {
+    id: string;
+    status: string;
+    verdict: string;
+    what_happened: string;
+    evidence: Record<string, unknown>;
+    retryable: boolean;
+    actions: ExplainAction[];
+}
+/** A send tested against every gate, with nothing sent and nothing spent. */
+export interface PreflightReport {
+    ok: boolean;
+    simulated: boolean;
+    error: {
+        code: string;
+        message: string;
+        fix: string;
+    } | null;
+    checks: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types, snake_case, mirroring what the API returns.
+ *
+ * Hand-written rather than imported from the server: a published client must
+ * not drag Fastify and Drizzle into a user's dependency tree. The guard against
+ * drift is the quickstart test, which runs this client against the real API.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The published version, as a literal.
+ *
+ * Read rather than imported from package.json so the shipped package needs no
+ * JSON import and no bundler has to resolve one. It cannot drift silently:
+ * `sdk_node_is_publishable_standalone` compares it to the manifest.
+ */
+export declare const SDK_VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,9 @@
+/**
+ * The published version, as a literal.
+ *
+ * Read rather than imported from package.json so the shipped package needs no
+ * JSON import and no bundler has to resolve one. It cannot drift silently:
+ * `sdk_node_is_publishable_standalone` compares it to the manifest.
+ */
+export const SDK_VERSION = '0.1.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/dist/webhook-signing.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Webhook signing — Stripe-shaped HMAC-SHA256.
+ *
+ * Header value format: `t=<unix seconds>,v1=<hmac_hex>`
+ * where hmac = HMAC-SHA256(secret, `${t}.${raw_body}`).
+ *
+ * Ported from a proven webhook-signing.ts; branding
+ * renamed X-Warmy-* -> X-AgentiSend-*, timestamps are unix seconds
+ * per the AgentiSend wire spec (PRD F4 / B2).
+ */
+/** 5-minute tolerance window for signature freshness. */
+export declare const SIGNATURE_TOLERANCE_SECONDS: number;
+export declare const SIGNATURE_HEADER = "x-agentisend-signature";
+export declare const EVENT_ID_HEADER = "x-agentisend-event-id";
+export declare const EVENT_TYPE_HEADER = "x-agentisend-event-type";
+export declare const TIMESTAMP_HEADER = "x-agentisend-timestamp";
+export declare const REPLAY_HEADER = "x-agentisend-replay";
+/**
+ * M5.11 — Svix's header set, beside ours, opt-in per endpoint.
+ *
+ * A receiver migrating from Resend already has a verifier: the `svix` library,
+ * or the twenty lines it documents. Making them rewrite it to accept our
+ * header is a migration cost with nothing on the other side of it, so an
+ * endpoint can ask for both and keep the verifier it has.
+ *
+ * The scheme is Svix's, exactly: HMAC-SHA256 over `${id}.${timestamp}.${body}`
+ * with the key being the base64-decoded bytes after the `whsec_` prefix, and
+ * the value a space-separated list of `v1,<base64>` — a list because Svix
+ * rotates by sending old and new signatures together.
+ */
+export declare const SVIX_ID_HEADER = "svix-id";
+export declare const SVIX_TIMESTAMP_HEADER = "svix-timestamp";
+export declare const SVIX_SIGNATURE_HEADER = "svix-signature";
+/** `v1,<base64 hmac>` over `${messageId}.${timestampSeconds}.${body}`. */
+export declare function signSvixPayload(secret: string, messageId: string, timestampSeconds: number, body: string): string;
+/** The three headers a Svix-shaped verifier reads. */
+export declare function generateSvixHeaders(secret: string, messageId: string, timestampSeconds: number, body: string): Record<string, string>;
+/** Sign a raw body at a given unix-second timestamp. Pure. */
+export declare function signWebhookPayload(secret: string, timestampSeconds: number, body: string): string;
+export interface VerifyOptions {
+    /** Current time in unix seconds. Defaults to Date.now()/1000. Injectable for tests. */
+    nowSeconds?: number;
+    /** Tolerance window in seconds. Defaults to 5 minutes. */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a signature header against a raw body. Timing-safe on the
+ * comparison path; every malformed input returns false, never throws.
+ */
+export declare function verifyWebhookSignature(secret: string, signatureHeader: string, body: string, options?: VerifyOptions): boolean;
+/** What a delivery may carry beside our own headers (M5.11). */
+export interface WebhookHeaderOptions {
+    /**
+     * Also sign this delivery the way Svix does, so a receiver migrating from
+     * Resend keeps the verifier it already has. Needs the secret and the body,
+     * because Svix signs the id and timestamp along with them.
+     */
+    svixCompat?: {
+        secret: string;
+        body: string;
+    };
+}
+/** Full delivery header set for an event payload. */
+export declare function generateWebhookHeaders(eventId: string, eventType: string, timestampSeconds: number, signature: string, replay?: boolean, options?: WebhookHeaderOptions): Record<string, string>;