perspectapi-ts-sdk 7.2.8 → 7.4.0

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 {