perspectapi-ts-sdk 7.2.6 → 7.4.0

package/src/v2/client/email-client.ts

@@ -8,11 +8,18 @@ import type { V2EmailSendParams, V2EmailSendResult } from '../types';
 export class EmailV2Client extends BaseV2Client {
 
   /**
-   * Send a transactional email using the site's configured email provider.
+   * Send a transactional email through the site's email provider.
    *
-   * Requires a server-side API key — never call this from a browser.
-   * The site must have an email provider configured in its settings.
-   * At least one of `html` or `text` must be provided.
+   * Requires a server-side API key — never call this from a browser. Sites
+   * without a configured provider fall back to the platform default with
+   * policy restrictions (owner-only recipients, daily quota).
+   *
+   * Provide content one of two ways (mutually exclusive):
+   *  - Raw: `subject` plus at least one of `html` / `text`.
+   *  - Template: `template_type` (published template for that type) or
+   *    `template_id` (published template by ID) plus optional `variables`; the
+   *    template is rendered server-side. `subject` is optional here and
+   *    overrides the rendered one.
    */
   async send(siteName: string, params: V2EmailSendParams): Promise<V2EmailSendResult> {
     return this.post<V2EmailSendResult>(

package/src/v2/client/email-templates-client.ts

@@ -0,0 +1,113 @@
+/**
+ * v2 Email Templates Client — versioned CRUD for site email templates.
+ *
+ * Mirrors the email_template_* MCP tools. Templates live under
+ * /sites/:siteName/email/templates. Use `listTypes` / `getTypeVariables` to
+ * discover the allowed substitution variables for each template type before
+ * authoring, then create/clone/publish versions.
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { CachePolicy } from '../../cache/types';
+import type {
+  V2EmailTemplate,
+  V2EmailTemplateType,
+  V2EmailTemplateType_Listing,
+  V2EmailTemplateListParams,
+  V2EmailTemplateCreateParams,
+  V2EmailTemplateCloneParams,
+  V2List,
+} from '../types';
+
+export class EmailTemplatesV2Client extends BaseV2Client {
+  private path(siteName: string, suffix = ''): string {
+    return this.sitePath(siteName, 'email', suffix ? `templates/${suffix}` : 'templates');
+  }
+
+  /** List every supported template type with its allowed variables. */
+  async listTypes(
+    siteName: string,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2List<V2EmailTemplateType_Listing>> {
+    return this.getList<V2EmailTemplateType_Listing>(
+      this.path(siteName, 'types'),
+      undefined,
+      cachePolicy,
+    );
+  }
+
+  /** Get the allowed variables for a single template type. */
+  async getTypeVariables(
+    siteName: string,
+    templateType: V2EmailTemplateType,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2EmailTemplateType_Listing> {
+    return this.getOne<V2EmailTemplateType_Listing>(
+      this.path(siteName, `types/${templateType}`),
+      undefined,
+      cachePolicy,
+    );
+  }
+
+  /** List template versions, optionally filtered by type and/or status. */
+  async list(
+    siteName: string,
+    params?: V2EmailTemplateListParams,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2List<V2EmailTemplate>> {
+    return this.getList<V2EmailTemplate>(this.path(siteName), params, cachePolicy);
+  }
+
+  /** Get a specific template version by ID (`etpl_…`). */
+  async get(
+    siteName: string,
+    templateId: string,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2EmailTemplate> {
+    return this.getOne<V2EmailTemplate>(
+      this.path(siteName, encodeURIComponent(templateId)),
+      undefined,
+      cachePolicy,
+    );
+  }
+
+  /** Get the currently published version for a template type. */
+  async getPublished(
+    siteName: string,
+    templateType: V2EmailTemplateType,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2EmailTemplate> {
+    return this.getOne<V2EmailTemplate>(
+      this.path(siteName, `published/${templateType}`),
+      undefined,
+      cachePolicy,
+    );
+  }
+
+  /** Create a new template version. */
+  async create(
+    siteName: string,
+    params: V2EmailTemplateCreateParams,
+  ): Promise<V2EmailTemplate> {
+    return this.post<V2EmailTemplate>(this.path(siteName), params);
+  }
+
+  /** Clone a template version, optionally overriding fields. */
+  async clone(
+    siteName: string,
+    templateId: string,
+    params?: V2EmailTemplateCloneParams,
+  ): Promise<V2EmailTemplate> {
+    return this.post<V2EmailTemplate>(
+      this.path(siteName, `${encodeURIComponent(templateId)}/clone`),
+      params ?? {},
+    );
+  }
+
+  /** Publish a template version (archives the previously published one). */
+  async publish(siteName: string, templateId: string): Promise<V2EmailTemplate> {
+    return this.post<V2EmailTemplate>(
+      this.path(siteName, `${encodeURIComponent(templateId)}/publish`),
+    );
+  }
+}

package/src/v2/client/newsletter-client.ts

@@ -6,11 +6,16 @@ import { BaseV2Client } from './base-v2-client';
 import type { CachePolicy } from '../../cache/types';
 import type {
   V2NewsletterSubscription, V2NewsletterList, V2NewsletterCampaign,
+  V2NewsletterSeries, V2NewsletterStatistics,
   V2PaginationParams, V2List, V2Deleted, V2NewsletterTrackingResponse,
   V2NewsletterListCreateParams, V2NewsletterListUpdateParams,
   V2NewsletterSyncInput, V2NewsletterSyncResult,
   V2NewsletterSubscriptionListMembershipUpdate,
   V2NewsletterImportRequest, V2NewsletterImportResult,
+  V2NewsletterCampaignCreateParams, V2NewsletterCampaignUpdateParams,
+  V2NewsletterSeriesCreateParams, V2NewsletterSeriesUpdateParams,
+  V2NewsletterStatisticsParams, V2NewsletterSubscriptionStatusUpdate,
+  V2NewsletterBulkParams, V2NewsletterBulkResult,
 } from '../types';
 
 export class NewsletterV2Client extends BaseV2Client {
@@ -206,4 +211,155 @@ export class NewsletterV2Client extends BaseV2Client {
       data,
     );
   }
+
+  // --- Lists (get by id) ---
+
+  async getListById(
+    siteName: string,
+    id: string,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2NewsletterList> {
+    return this.getOne<V2NewsletterList>(
+      this.sitePath(siteName, 'newsletter', `lists/${encodeURIComponent(id)}`),
+      undefined,
+      cachePolicy,
+    );
+  }
+
+  // --- Subscriptions (admin: lookup / status / delete / bulk) ---
+
+  async getSubscriptionByEmail(
+    siteName: string,
+    email: string,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2NewsletterSubscription> {
+    return this.getOne<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', 'subscriptions/by-email'),
+      { email },
+      cachePolicy,
+    );
+  }
+
+  async updateSubscriptionStatus(
+    siteName: string,
+    id: string,
+    data: V2NewsletterSubscriptionStatusUpdate,
+  ): Promise<V2NewsletterSubscription> {
+    return this.post<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', `subscriptions/${encodeURIComponent(id)}/status`),
+      data,
+    );
+  }
+
+  async deleteSubscription(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(
+      this.sitePath(siteName, 'newsletter', `subscriptions/${encodeURIComponent(id)}`),
+    );
+  }
+
+  async bulkUpdateSubscriptions(
+    siteName: string,
+    data: V2NewsletterBulkParams,
+  ): Promise<V2NewsletterBulkResult> {
+    return this.post<V2NewsletterBulkResult>(
+      this.sitePath(siteName, 'newsletter', 'subscriptions/bulk'),
+      data,
+    );
+  }
+
+  // --- Statistics ---
+
+  async getStatistics(
+    siteName: string,
+    params?: V2NewsletterStatisticsParams,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2NewsletterStatistics> {
+    return this.getOne<V2NewsletterStatistics>(
+      this.sitePath(siteName, 'newsletter', 'statistics'),
+      params,
+      cachePolicy,
+    );
+  }
+
+  // --- Campaigns (create / update / delete) ---
+
+  async createCampaign(
+    siteName: string,
+    data: V2NewsletterCampaignCreateParams,
+  ): Promise<V2NewsletterCampaign> {
+    return this.post<V2NewsletterCampaign>(
+      this.sitePath(siteName, 'newsletter', 'campaigns'),
+      data,
+    );
+  }
+
+  async updateCampaign(
+    siteName: string,
+    id: string,
+    data: V2NewsletterCampaignUpdateParams,
+  ): Promise<V2NewsletterCampaign> {
+    return this.patchOne<V2NewsletterCampaign>(
+      this.sitePath(siteName, 'newsletter', `campaigns/${encodeURIComponent(id)}`),
+      data,
+    );
+  }
+
+  async deleteCampaign(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(
+      this.sitePath(siteName, 'newsletter', `campaigns/${encodeURIComponent(id)}`),
+    );
+  }
+
+  // --- Series ---
+
+  async listSeries(
+    siteName: string,
+    params?: { status?: 'active' | 'paused' | 'archived' },
+    cachePolicy?: CachePolicy,
+  ): Promise<V2List<V2NewsletterSeries>> {
+    return this.getList<V2NewsletterSeries>(
+      this.sitePath(siteName, 'newsletter', 'series'),
+      params,
+      cachePolicy,
+    );
+  }
+
+  async getSeries(
+    siteName: string,
+    id: string,
+    cachePolicy?: CachePolicy,
+  ): Promise<V2NewsletterSeries> {
+    return this.getOne<V2NewsletterSeries>(
+      this.sitePath(siteName, 'newsletter', `series/${encodeURIComponent(id)}`),
+      undefined,
+      cachePolicy,
+    );
+  }
+
+  async createSeries(
+    siteName: string,
+    data: V2NewsletterSeriesCreateParams,
+  ): Promise<V2NewsletterSeries> {
+    return this.post<V2NewsletterSeries>(
+      this.sitePath(siteName, 'newsletter', 'series'),
+      data,
+    );
+  }
+
+  async updateSeries(
+    siteName: string,
+    id: string,
+    data: V2NewsletterSeriesUpdateParams,
+  ): Promise<V2NewsletterSeries> {
+    return this.patchOne<V2NewsletterSeries>(
+      this.sitePath(siteName, 'newsletter', `series/${encodeURIComponent(id)}`),
+      data,
+    );
+  }
+
+  async deleteSeries(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(
+      this.sitePath(siteName, 'newsletter', `series/${encodeURIComponent(id)}`),
+    );
+  }
 }

package/src/v2/index.ts

@@ -30,6 +30,7 @@ import { WebhooksV2Client } from './client/webhooks-client';
 import { SubscriptionsV2Client } from './client/subscriptions-client';
 import { CreditsV2Client } from './client/credits-client';
 import { EmailV2Client } from './client/email-client';
+import { EmailTemplatesV2Client } from './client/email-templates-client';
 
 export interface PerspectApiV2Config extends PerspectApiConfig {
   cache?: CacheConfig;
@@ -54,6 +55,7 @@ export class PerspectApiV2Client {
   readonly subscriptions: SubscriptionsV2Client;
   readonly credits: CreditsV2Client;
   readonly email: EmailV2Client;
+  readonly emailTemplates: EmailTemplatesV2Client;
 
   constructor(config: PerspectApiV2Config) {
     // Ensure base URL points to /api/v2
@@ -82,6 +84,7 @@ export class PerspectApiV2Client {
     this.subscriptions = new SubscriptionsV2Client(this.http, basePath, cache);
     this.credits = new CreditsV2Client(this.http, basePath, cache);
     this.email = new EmailV2Client(this.http, basePath, cache);
+    this.emailTemplates = new EmailTemplatesV2Client(this.http, basePath, cache);
   }
 
   /** Update the JWT token for authenticated requests. */
@@ -124,3 +127,4 @@ export { WebhooksV2Client } from './client/webhooks-client';
 export { SubscriptionsV2Client } from './client/subscriptions-client';
 export { CreditsV2Client } from './client/credits-client';
 export { EmailV2Client } from './client/email-client';
+export { EmailTemplatesV2Client } from './client/email-templates-client';

package/src/v2/types.ts

@@ -507,23 +507,77 @@ export interface V2NewsletterList extends V2Object {
   updated_at: string | null;
 }
 
+export type V2NewsletterCampaignStatus =
+  | "draft"
+  | "scheduled"
+  | "sending"
+  | "sent"
+  | "cancelled";
+
 export interface V2NewsletterCampaign extends V2Object {
   object: "newsletter_campaign";
   name: string;
   slug: string | null;
+  slug_prefix?: string | null;
   subject: string;
   preview_text: string | null;
-  status: string;
+  markdown_content?: string | null;
+  series_id?: string | null;
+  series_name?: string | null;
+  template_id?: string | null;
+  list_ids?: string[];
+  tags?: string[] | null;
+  notes?: string | null;
+  from_name?: string | null;
+  from_email?: string | null;
+  reply_to_email?: string | null;
+  send_to_all?: boolean;
+  status: V2NewsletterCampaignStatus | string;
+  scheduled_at?: string | null;
   sent_at: string | null;
   completed_at: string | null;
   total_recipients: number;
   sent_count: number;
+  delivered_count?: number;
   opened_count: number;
   clicked_count: number;
+  unsubscribed_count?: number;
+  bounced_count?: number;
+  complained_count?: number;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2NewsletterSeries extends V2Object {
+  object: "newsletter_series";
+  name: string;
+  description: string | null;
+  list_ids: string[];
+  from_name: string | null;
+  from_email: string | null;
+  reply_to_email: string | null;
+  subject_prefix: string | null;
+  cadence: "manual" | "daily" | "weekly" | "monthly" | string;
+  timezone: string | null;
+  send_time: string | null;
+  day_of_week: number | null;
+  day_of_month: number | null;
+  status: "active" | "paused" | "archived" | string;
+  last_sent_at: string | null;
+  next_send_at: string | null;
+  tags: string[] | null;
+  notes: string | null;
   created_at: string | null;
   updated_at: string | null;
 }
 
+export interface V2NewsletterStatistics {
+  object: "newsletter_statistics";
+  total: number;
+  by_status: Record<string, number>;
+  recent_activity: Array<{ date: string; count: number }>;
+}
+
 export interface V2NewsletterTrackingResponse {
   success: boolean;
 }
@@ -606,6 +660,93 @@ export interface V2NewsletterImportResult {
   }>;
 }
 
+// --- Newsletter campaigns / series / statistics (admin) ---
+
+export interface V2NewsletterCampaignCreateParams {
+  campaign_name: string;
+  subject: string;
+  /** Markdown body; rendered to HTML/text server-side. */
+  markdown_content: string;
+  slug?: string;
+  slug_prefix?: string | null;
+  /**
+   * `scheduled` requires a `scheduled_at`, the newsletter plan entitlement, and
+   * the `newsletters.publish` permission on the API key (creating/updating a
+   * draft only needs `newsletters.create`/`newsletters.update`).
+   */
+  status?: "draft" | "scheduled" | "cancelled";
+  /** Local datetime (YYYY-MM-DDTHH:MM[:SS]) in the site/series timezone. */
+  scheduled_at?: string | null;
+  preview_text?: string;
+  from_name?: string;
+  from_email?: string;
+  reply_to_email?: string;
+  /** Newsletter template version ID (`etpl_…`). */
+  template_id?: string | null;
+  /** Series ID (`nsr_…`). */
+  series_id?: string | null;
+  /** Target list IDs (`nll_…`). */
+  list_ids?: string[];
+  tags?: string[];
+  notes?: string;
+}
+
+export type V2NewsletterCampaignUpdateParams = Partial<
+  Omit<V2NewsletterCampaignCreateParams, "campaign_name" | "subject" | "markdown_content">
+> & {
+  campaign_name?: string;
+  subject?: string;
+  markdown_content?: string;
+};
+
+export interface V2NewsletterSeriesCreateParams {
+  series_name: string;
+  description?: string;
+  status?: "active" | "paused" | "archived";
+  cadence?: "manual" | "daily" | "weekly" | "monthly";
+  timezone?: string;
+  send_time?: string;
+  day_of_week?: number;
+  day_of_month?: number;
+  next_send_at?: string | null;
+  list_ids?: string[];
+  from_name?: string;
+  from_email?: string;
+  reply_to_email?: string;
+  subject_prefix?: string;
+  tags?: string[];
+  notes?: string;
+}
+
+export type V2NewsletterSeriesUpdateParams = Partial<V2NewsletterSeriesCreateParams>;
+
+export interface V2NewsletterStatisticsParams {
+  start_date?: string;
+  end_date?: string;
+  list_id?: string;
+}
+
+export interface V2NewsletterSubscriptionStatusUpdate {
+  status: "confirmed" | "unsubscribed" | "bounced" | "complained";
+  notes?: string;
+}
+
+export interface V2NewsletterBulkParams {
+  ids: string[];
+  action: "confirm" | "unsubscribe" | "delete" | "add_to_list" | "remove_from_list";
+  /** Required for add_to_list / remove_from_list. */
+  list_id?: string;
+}
+
+export interface V2NewsletterBulkResult {
+  object: "newsletter_bulk_result";
+  succeeded: number;
+  failed: number;
+  /** Per-id failures (id + reason) for the subscriptions that did not apply. */
+  failures: Array<{ id: string; error: string }>;
+  [key: string]: unknown;
+}
+
 // --- Contact ---
 
 export interface V2ContactSubmission extends V2Object {
@@ -818,15 +959,105 @@ export interface V2GrantCreditResult {
 
 // --- Email ---
 
+export type V2EmailTemplateType =
+  | "order_customer_receipt"
+  | "order_admin_notification"
+  | "signup_welcome"
+  | "order_fulfillment_notification"
+  | "order_cancellation_notification"
+  | "subscription_cancelled"
+  | "subscription_cancellation_admin_notification"
+  | "subscription_plan_changed"
+  | "subscription_plan_changed_admin_notification"
+  | "newsletter"
+  | "customer_support";
+
+export type V2EmailTemplateStatus = "draft" | "published" | "archived";
+
 export interface V2EmailSendParams {
   to: string | string[];
-  subject: string;
+  /** Required for raw sends; optional (overrides the rendered subject) for template sends. */
+  subject?: string;
   html?: string;
   text?: string;
   from?: string;
   reply_to?: string;
   cc?: string | string[];
   bcc?: string | string[];
+  /**
+   * Template-based send. Provide exactly one of `template_id` (a published
+   * template by ID) or `template_type` (the published template for that type);
+   * the template is rendered server-side with `variables` substituted in.
+   * Mutually exclusive with `html`/`text`.
+   */
+  template_id?: string;
+  template_type?: V2EmailTemplateType;
+  variables?: Record<string, string | number | null>;
+  /**
+   * When true, every placeholder referenced by the template must be present in
+   * `variables` (null counts as provided) — otherwise the API rejects the send
+   * instead of rendering the missing placeholders as empty strings.
+   */
+  strict?: boolean;
+}
+
+export interface V2EmailTemplate extends V2Object {
+  object: "email_template";
+  template_type: V2EmailTemplateType;
+  template_name: string;
+  description: string | null;
+  subject_template: string;
+  html_template: string;
+  text_template: string;
+  status: V2EmailTemplateStatus;
+  version: number;
+  variables: string[];
+  created_by: string | null;
+  created_at: string;
+  updated_at: string;
+  published_at: string | null;
+  /** Present on clone responses: the source template ID. */
+  source_template_id?: string;
+}
+
+export interface V2EmailTemplateType_Listing {
+  object: "email_template_type";
+  template_type: V2EmailTemplateType;
+  variables: string[];
+}
+
+export interface V2EmailTemplateListParams {
+  template_type?: V2EmailTemplateType;
+  status?: V2EmailTemplateStatus;
+}
+
+export interface V2EmailTemplateCreateParams {
+  template_type: V2EmailTemplateType;
+  template_name: string;
+  subject_template: string;
+  html_template: string;
+  text_template: string;
+  description?: string;
+  /**
+   * Defaults to "draft". Creating directly into "published" additionally
+   * requires the `templates.publish` permission (and the custom-email plan
+   * entitlement, like all template mutations); otherwise the API returns 403.
+   */
+  status?: "draft" | "published";
+}
+
+export interface V2EmailTemplateCloneParams {
+  template_name?: string;
+  subject_template?: string;
+  html_template?: string;
+  text_template?: string;
+  description?: string;
+  /**
+   * Defaults to "draft". Creating directly into "published" additionally
+   * requires the `templates.publish` permission (and the custom-email plan
+   * entitlement, like all template mutations); otherwise the API returns 403.
+   */
+  status?: "draft" | "published";
 }
 
 export interface V2EmailSendResult {