zupost 0.6.1 → 0.7.0

package/dist/index.d.mts

@@ -9,9 +9,9 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 declare class HttpClient {
     #private;
     constructor(apiKey: string, baseUrl: string, userAgent: string);
-    request<T = unknown>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
+    request<T = unknown>(path: string, method: HttpMethod, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
     get<T = unknown>(path: string): Promise<T>;
-    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    post<T = unknown>(path: string, body: unknown, extraHeaders?: Record<string, string>): Promise<T>;
     patch<T = unknown>(path: string, body: unknown): Promise<T>;
     delete<T = unknown>(path: string, body?: unknown): Promise<T>;
 }
@@ -113,6 +113,12 @@ interface SendEmailOptions {
         /** The file content as a Base64-encoded string (e.g., "JVBERi0xLjQKJ..."). */
         content: string;
     }>;
+    /**
+     * zupost Platform only: a domain grant token obtained from a completed
+     * onboarding session. Set it to send from an end customer's domain that was
+     * connected through your platform. The `from` address must be on that domain.
+     */
+    domainToken?: string;
 }
 /**
  * Response from sending an email.
@@ -799,6 +805,99 @@ declare class Inbound {
     };
 }
 
+/** Optional visual customization of the zupost-hosted connect page. */
+interface OnboardingSessionBranding {
+    brandName?: string;
+    brandLogoUrl?: string;
+    brandColor?: string;
+}
+interface CreateOnboardingSessionOptions {
+    /**
+     * URL the end user is redirected back to after finishing the flow. Its host
+     * must be in your platform organization's allowed redirect hosts. zupost
+     * appends an `onboarding_session_id` query parameter on return.
+     */
+    returnUrl: string;
+    /** Optional domain to pre-fill on the connect page, e.g. `customer.com`. */
+    domain?: string;
+    /** Optional branding overrides for the hosted page. */
+    branding?: OnboardingSessionBranding;
+}
+interface CreateOnboardingSessionResponse {
+    /** The onboarding session id; use it with {@link OnboardingSessions.get}. */
+    id: string;
+    /** The zupost-hosted URL to redirect your end user to. */
+    url: string;
+    /** ISO timestamp after which the session can no longer be completed. */
+    expiresAt: string;
+}
+type OnboardingSessionStatus = 'OPEN' | 'COMPLETED' | 'EXPIRED';
+type GrantStatus = 'PENDING' | 'ACTIVE' | 'REVOKED';
+/** The grant produced once a session completes. */
+interface OnboardingSessionGrant {
+    id: string;
+    /**
+     * The secret domain-grant token used to send from the connected domain.
+     * Present once the session is `COMPLETED`.
+     */
+    token: string | null;
+    status: GrantStatus;
+    domainName: string | null;
+}
+interface OnboardingSession {
+    id: string;
+    status: OnboardingSessionStatus;
+    domainName: string | null;
+    expiresAt: string;
+    /** Populated once `status` is `COMPLETED`. */
+    grant: OnboardingSessionGrant | null;
+}
+
+/**
+ * Platform API.
+ *
+ * For zupost Platform organizations that build products on top of zupost. Start
+ * a hosted, no-account domain-connect session for one of your end customers,
+ * redirect them to it, then exchange the completed session for a domain grant
+ * token you store and send with (via `zupost.emails.send({ ..., domainToken })`).
+ */
+declare class Platform {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Hosted domain-connect onboarding sessions. */
+    readonly onboardingSessions: {
+        /**
+         * Start a hosted domain-connect onboarding session. Redirect your end user
+         * to the returned `url`; when they finish, zupost sends them back to your
+         * `returnUrl` with an `onboarding_session_id` query parameter that you can
+         * exchange via {@link get}.
+         *
+         * @example
+         * ```typescript
+         * const session = await zupost.platform.onboardingSessions.create({
+         *   returnUrl: 'https://app.example.com/zupost/return',
+         *   domain: 'customer.com',
+         * });
+         * // redirect the user to session.url
+         * ```
+         */
+        create: (options: CreateOnboardingSessionOptions) => Promise<CreateOnboardingSessionResponse>;
+        /**
+         * Fetch an onboarding session. Once its `status` is `COMPLETED`, read
+         * `grant.token` — the credential you persist and send with.
+         *
+         * @example
+         * ```typescript
+         * const session = await zupost.platform.onboardingSessions.get(id);
+         * if (session.status === 'COMPLETED') {
+         *   await store(session.domainName, session.grant?.token);
+         * }
+         * ```
+         */
+        get: (id: string) => Promise<OnboardingSession>;
+    };
+}
+
 interface ZupostOptions {
     /**
      * Custom API URL. Defaults to 'https://api.zupost.com'.
@@ -835,6 +934,12 @@ declare class Zupost {
      * your own webhook through an inbound channel.
      */
     readonly inbound: Inbound;
+    /**
+     * Platform API. For zupost Platform organizations: run hosted domain-connect
+     * onboarding for your end customers and obtain domain grant tokens to send
+     * on their behalf.
+     */
+    readonly platform: Platform;
     constructor(apiKey: string, options?: ZupostOptions);
 }
 
@@ -904,4 +1009,4 @@ declare function defineSequence<TSteps extends Record<string, SequenceStep>>(def
     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 };
+export { type BranchCondition, type Contact, type ContactEvent, type ContactEventType, type ContactExport, type ContactTag, type CreateContactOptions, type CreateDomainOptions, type CreateInboundChannelOptions, type CreateOnboardingSessionOptions, type CreateOnboardingSessionResponse, type CreateSequenceOptions, type DeleteDomainResponse, type Domain, type DomainDnsRecord, type DomainDnsRecordType, type DomainVerificationStatus, type EmailRecipientType, type ForgetContactResponse, type GrantStatus, type InboundChannel, type ListContactsOptions, type ListContactsResponse, type ListEventsOptions, type ListEventsResponse, type ListRunsOptions, type ListRunsResponse, type ListSequencesOptions, type ListSequencesResponse, type OnboardingSession, type OnboardingSessionBranding, type OnboardingSessionGrant, type OnboardingSessionStatus, 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 };

package/dist/index.d.ts

@@ -9,9 +9,9 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 declare class HttpClient {
     #private;
     constructor(apiKey: string, baseUrl: string, userAgent: string);
-    request<T = unknown>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
+    request<T = unknown>(path: string, method: HttpMethod, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
     get<T = unknown>(path: string): Promise<T>;
-    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    post<T = unknown>(path: string, body: unknown, extraHeaders?: Record<string, string>): Promise<T>;
     patch<T = unknown>(path: string, body: unknown): Promise<T>;
     delete<T = unknown>(path: string, body?: unknown): Promise<T>;
 }
@@ -113,6 +113,12 @@ interface SendEmailOptions {
         /** The file content as a Base64-encoded string (e.g., "JVBERi0xLjQKJ..."). */
         content: string;
     }>;
+    /**
+     * zupost Platform only: a domain grant token obtained from a completed
+     * onboarding session. Set it to send from an end customer's domain that was
+     * connected through your platform. The `from` address must be on that domain.
+     */
+    domainToken?: string;
 }
 /**
  * Response from sending an email.
@@ -799,6 +805,99 @@ declare class Inbound {
     };
 }
 
+/** Optional visual customization of the zupost-hosted connect page. */
+interface OnboardingSessionBranding {
+    brandName?: string;
+    brandLogoUrl?: string;
+    brandColor?: string;
+}
+interface CreateOnboardingSessionOptions {
+    /**
+     * URL the end user is redirected back to after finishing the flow. Its host
+     * must be in your platform organization's allowed redirect hosts. zupost
+     * appends an `onboarding_session_id` query parameter on return.
+     */
+    returnUrl: string;
+    /** Optional domain to pre-fill on the connect page, e.g. `customer.com`. */
+    domain?: string;
+    /** Optional branding overrides for the hosted page. */
+    branding?: OnboardingSessionBranding;
+}
+interface CreateOnboardingSessionResponse {
+    /** The onboarding session id; use it with {@link OnboardingSessions.get}. */
+    id: string;
+    /** The zupost-hosted URL to redirect your end user to. */
+    url: string;
+    /** ISO timestamp after which the session can no longer be completed. */
+    expiresAt: string;
+}
+type OnboardingSessionStatus = 'OPEN' | 'COMPLETED' | 'EXPIRED';
+type GrantStatus = 'PENDING' | 'ACTIVE' | 'REVOKED';
+/** The grant produced once a session completes. */
+interface OnboardingSessionGrant {
+    id: string;
+    /**
+     * The secret domain-grant token used to send from the connected domain.
+     * Present once the session is `COMPLETED`.
+     */
+    token: string | null;
+    status: GrantStatus;
+    domainName: string | null;
+}
+interface OnboardingSession {
+    id: string;
+    status: OnboardingSessionStatus;
+    domainName: string | null;
+    expiresAt: string;
+    /** Populated once `status` is `COMPLETED`. */
+    grant: OnboardingSessionGrant | null;
+}
+
+/**
+ * Platform API.
+ *
+ * For zupost Platform organizations that build products on top of zupost. Start
+ * a hosted, no-account domain-connect session for one of your end customers,
+ * redirect them to it, then exchange the completed session for a domain grant
+ * token you store and send with (via `zupost.emails.send({ ..., domainToken })`).
+ */
+declare class Platform {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Hosted domain-connect onboarding sessions. */
+    readonly onboardingSessions: {
+        /**
+         * Start a hosted domain-connect onboarding session. Redirect your end user
+         * to the returned `url`; when they finish, zupost sends them back to your
+         * `returnUrl` with an `onboarding_session_id` query parameter that you can
+         * exchange via {@link get}.
+         *
+         * @example
+         * ```typescript
+         * const session = await zupost.platform.onboardingSessions.create({
+         *   returnUrl: 'https://app.example.com/zupost/return',
+         *   domain: 'customer.com',
+         * });
+         * // redirect the user to session.url
+         * ```
+         */
+        create: (options: CreateOnboardingSessionOptions) => Promise<CreateOnboardingSessionResponse>;
+        /**
+         * Fetch an onboarding session. Once its `status` is `COMPLETED`, read
+         * `grant.token` — the credential you persist and send with.
+         *
+         * @example
+         * ```typescript
+         * const session = await zupost.platform.onboardingSessions.get(id);
+         * if (session.status === 'COMPLETED') {
+         *   await store(session.domainName, session.grant?.token);
+         * }
+         * ```
+         */
+        get: (id: string) => Promise<OnboardingSession>;
+    };
+}
+
 interface ZupostOptions {
     /**
      * Custom API URL. Defaults to 'https://api.zupost.com'.
@@ -835,6 +934,12 @@ declare class Zupost {
      * your own webhook through an inbound channel.
      */
     readonly inbound: Inbound;
+    /**
+     * Platform API. For zupost Platform organizations: run hosted domain-connect
+     * onboarding for your end customers and obtain domain grant tokens to send
+     * on their behalf.
+     */
+    readonly platform: Platform;
     constructor(apiKey: string, options?: ZupostOptions);
 }
 
@@ -904,4 +1009,4 @@ declare function defineSequence<TSteps extends Record<string, SequenceStep>>(def
     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 };
+export { type BranchCondition, type Contact, type ContactEvent, type ContactEventType, type ContactExport, type ContactTag, type CreateContactOptions, type CreateDomainOptions, type CreateInboundChannelOptions, type CreateOnboardingSessionOptions, type CreateOnboardingSessionResponse, type CreateSequenceOptions, type DeleteDomainResponse, type Domain, type DomainDnsRecord, type DomainDnsRecordType, type DomainVerificationStatus, type EmailRecipientType, type ForgetContactResponse, type GrantStatus, type InboundChannel, type ListContactsOptions, type ListContactsResponse, type ListEventsOptions, type ListEventsResponse, type ListRunsOptions, type ListRunsResponse, type ListSequencesOptions, type ListSequencesResponse, type OnboardingSession, type OnboardingSessionBranding, type OnboardingSessionGrant, type OnboardingSessionStatus, 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 };

package/dist/index.js

@@ -79,7 +79,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.6.1";
+var version = "0.7.0";
 
 // src/errors.ts
 var ZupostError = class _ZupostError extends Error {
@@ -145,13 +145,18 @@ var HttpClient = class {
       "User-Agent": userAgent
     });
   }
-  request(path, method, body) {
+  request(path, method, body, extraHeaders) {
     return __async(this, null, function* () {
       const url = `${__privateGet(this, _baseUrl)}/${path.replace(/^\//, "")}`;
       const headers = new Headers(__privateGet(this, _defaultHeaders));
       if (method !== "GET") {
         headers.set("Idempotency-Key", crypto.randomUUID());
       }
+      if (extraHeaders) {
+        for (const [key, value] of Object.entries(extraHeaders)) {
+          headers.set(key, value);
+        }
+      }
       const init = { method, headers };
       if (body !== void 0) {
         init.body = JSON.stringify(body);
@@ -183,9 +188,9 @@ var HttpClient = class {
       return this.request(path, "GET");
     });
   }
-  post(path, body) {
+  post(path, body, extraHeaders) {
     return __async(this, null, function* () {
-      return this.request(path, "POST", body);
+      return this.request(path, "POST", body, extraHeaders);
     });
   }
   patch(path, body) {
@@ -268,9 +273,7 @@ var Emails = class {
         throw new Error("Provide only one of html, markdown, or react");
       }
       if (inlineCount === 0 && !options.templateId && !options.text) {
-        throw new Error(
-          "Provide one of html, markdown, react, text, or templateId"
-        );
+        throw new Error("Provide one of html, markdown, react, text, or templateId");
       }
       const payload = __spreadValues({}, options);
       if (options.react) {
@@ -279,6 +282,13 @@ var Emails = class {
         delete payload.react;
         delete payload.reactOptions;
       }
+      const { domainToken } = options;
+      delete payload.domainToken;
+      if (domainToken) {
+        return this.http.post("email/send", payload, {
+          "X-Zupost-Domain-Token": domainToken
+        });
+      }
       return this.http.post("email/send", payload);
     });
   }
@@ -633,6 +643,54 @@ var Inbound = class {
   }
 };
 
+// src/platform/platform.ts
+var Platform = class {
+  constructor(http) {
+    this.http = http;
+    /** Hosted domain-connect onboarding sessions. */
+    this.onboardingSessions = {
+      /**
+       * Start a hosted domain-connect onboarding session. Redirect your end user
+       * to the returned `url`; when they finish, zupost sends them back to your
+       * `returnUrl` with an `onboarding_session_id` query parameter that you can
+       * exchange via {@link get}.
+       *
+       * @example
+       * ```typescript
+       * const session = await zupost.platform.onboardingSessions.create({
+       *   returnUrl: 'https://app.example.com/zupost/return',
+       *   domain: 'customer.com',
+       * });
+       * // redirect the user to session.url
+       * ```
+       */
+      create: (options) => __async(this, null, function* () {
+        return this.http.post(
+          "/platform/onboarding-sessions",
+          options
+        );
+      }),
+      /**
+       * Fetch an onboarding session. Once its `status` is `COMPLETED`, read
+       * `grant.token` — the credential you persist and send with.
+       *
+       * @example
+       * ```typescript
+       * const session = await zupost.platform.onboardingSessions.get(id);
+       * if (session.status === 'COMPLETED') {
+       *   await store(session.domainName, session.grant?.token);
+       * }
+       * ```
+       */
+      get: (id) => __async(this, null, function* () {
+        return this.http.get(
+          `/platform/onboarding-sessions/${encodeURIComponent(id)}`
+        );
+      })
+    };
+  }
+};
+
 // src/zupost.ts
 var _client;
 var Zupost = class {
@@ -650,6 +708,7 @@ var Zupost = class {
     this.sequences = new Sequences(__privateGet(this, _client));
     this.domains = new Domains(__privateGet(this, _client));
     this.inbound = new Inbound(__privateGet(this, _client));
+    this.platform = new Platform(__privateGet(this, _client));
   }
 };
 _client = new WeakMap();

package/dist/index.mjs

@@ -44,7 +44,7 @@ var __async = (__this, __arguments, generator) => {
 };
 
 // package.json
-var version = "0.6.1";
+var version = "0.7.0";
 
 // src/errors.ts
 var ZupostError = class _ZupostError extends Error {
@@ -110,13 +110,18 @@ var HttpClient = class {
       "User-Agent": userAgent
     });
   }
-  request(path, method, body) {
+  request(path, method, body, extraHeaders) {
     return __async(this, null, function* () {
       const url = `${__privateGet(this, _baseUrl)}/${path.replace(/^\//, "")}`;
       const headers = new Headers(__privateGet(this, _defaultHeaders));
       if (method !== "GET") {
         headers.set("Idempotency-Key", crypto.randomUUID());
       }
+      if (extraHeaders) {
+        for (const [key, value] of Object.entries(extraHeaders)) {
+          headers.set(key, value);
+        }
+      }
       const init = { method, headers };
       if (body !== void 0) {
         init.body = JSON.stringify(body);
@@ -148,9 +153,9 @@ var HttpClient = class {
       return this.request(path, "GET");
     });
   }
-  post(path, body) {
+  post(path, body, extraHeaders) {
     return __async(this, null, function* () {
-      return this.request(path, "POST", body);
+      return this.request(path, "POST", body, extraHeaders);
     });
   }
   patch(path, body) {
@@ -233,9 +238,7 @@ var Emails = class {
         throw new Error("Provide only one of html, markdown, or react");
       }
       if (inlineCount === 0 && !options.templateId && !options.text) {
-        throw new Error(
-          "Provide one of html, markdown, react, text, or templateId"
-        );
+        throw new Error("Provide one of html, markdown, react, text, or templateId");
       }
       const payload = __spreadValues({}, options);
       if (options.react) {
@@ -244,6 +247,13 @@ var Emails = class {
         delete payload.react;
         delete payload.reactOptions;
       }
+      const { domainToken } = options;
+      delete payload.domainToken;
+      if (domainToken) {
+        return this.http.post("email/send", payload, {
+          "X-Zupost-Domain-Token": domainToken
+        });
+      }
       return this.http.post("email/send", payload);
     });
   }
@@ -598,6 +608,54 @@ var Inbound = class {
   }
 };
 
+// src/platform/platform.ts
+var Platform = class {
+  constructor(http) {
+    this.http = http;
+    /** Hosted domain-connect onboarding sessions. */
+    this.onboardingSessions = {
+      /**
+       * Start a hosted domain-connect onboarding session. Redirect your end user
+       * to the returned `url`; when they finish, zupost sends them back to your
+       * `returnUrl` with an `onboarding_session_id` query parameter that you can
+       * exchange via {@link get}.
+       *
+       * @example
+       * ```typescript
+       * const session = await zupost.platform.onboardingSessions.create({
+       *   returnUrl: 'https://app.example.com/zupost/return',
+       *   domain: 'customer.com',
+       * });
+       * // redirect the user to session.url
+       * ```
+       */
+      create: (options) => __async(this, null, function* () {
+        return this.http.post(
+          "/platform/onboarding-sessions",
+          options
+        );
+      }),
+      /**
+       * Fetch an onboarding session. Once its `status` is `COMPLETED`, read
+       * `grant.token` — the credential you persist and send with.
+       *
+       * @example
+       * ```typescript
+       * const session = await zupost.platform.onboardingSessions.get(id);
+       * if (session.status === 'COMPLETED') {
+       *   await store(session.domainName, session.grant?.token);
+       * }
+       * ```
+       */
+      get: (id) => __async(this, null, function* () {
+        return this.http.get(
+          `/platform/onboarding-sessions/${encodeURIComponent(id)}`
+        );
+      })
+    };
+  }
+};
+
 // src/zupost.ts
 var _client;
 var Zupost = class {
@@ -615,6 +673,7 @@ var Zupost = class {
     this.sequences = new Sequences(__privateGet(this, _client));
     this.domains = new Domains(__privateGet(this, _client));
     this.inbound = new Inbound(__privateGet(this, _client));
+    this.platform = new Platform(__privateGet(this, _client));
   }
 };
 _client = new WeakMap();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zupost",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Node.js SDK for Zupost",
   "engines": {
     "node": ">=20"