perspectapi-ts-sdk 7.2.8 → 7.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -57,6 +57,60 @@ const contacts = await client.contacts.list('my-site', {
57
57
  });
58
58
  ```
59
59
 
60
+ ## Email & Newsletters
61
+
62
+ Send raw or template-based transactional email, and manage email templates,
63
+ newsletter campaigns, series, and statistics — matching the MCP tool surface.
64
+
65
+ ```typescript
66
+ // Raw send
67
+ await client.email.send('my-site', {
68
+ to: 'user@example.com',
69
+ subject: 'Hello',
70
+ html: '<p>Hi there</p>',
71
+ });
72
+
73
+ // Template-based send (renders the published `customer_support` template).
74
+ // Provide every variable the template references — including any used in its
75
+ // subject line. A blank rendered subject is rejected; pass `subject` to
76
+ // override, and `strict: true` to fail fast on any missing variable.
77
+ await client.email.send('my-site', {
78
+ to: 'user@example.com',
79
+ template_type: 'customer_support',
80
+ subject: 'Re: your request',
81
+ variables: {
82
+ support_subject: 'Re: your request',
83
+ support_message_html: '<p>How can we help?</p>',
84
+ support_message_text: 'How can we help?',
85
+ },
86
+ strict: true,
87
+ });
88
+
89
+ // Author and publish an email template
90
+ const draft = await client.emailTemplates.create('my-site', {
91
+ template_type: 'newsletter',
92
+ template_name: 'Monthly digest',
93
+ subject_template: '{{campaign_subject}}',
94
+ html_template: '<main>{{{campaign_content_html}}}</main>',
95
+ text_template: '{{campaign_content_text}}',
96
+ });
97
+ await client.emailTemplates.publish('my-site', draft.id);
98
+
99
+ // Create and schedule a newsletter campaign.
100
+ // Scheduling requires the newsletter plan entitlement AND a key with the
101
+ // `newsletters.publish` permission; a plain draft only needs `newsletters.create`.
102
+ const campaign = await client.newsletter.createCampaign('my-site', {
103
+ campaign_name: 'July update',
104
+ subject: 'What shipped in July',
105
+ markdown_content: '# Highlights\n\n- ...',
106
+ status: 'scheduled',
107
+ scheduled_at: '2026-07-01T09:00',
108
+ list_ids: ['nll_...'],
109
+ });
110
+
111
+ const stats = await client.newsletter.getStatistics('my-site');
112
+ ```
113
+
60
114
  ## Error Handling
61
115
 
62
116
  ```typescript
@@ -96,6 +96,8 @@ var HttpClient = class {
96
96
  }
97
97
  this.dbg(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
98
98
  let lastError;
99
+ const method = (options.method || "GET").toUpperCase();
100
+ const isIdempotent = method === "GET" || method === "HEAD";
99
101
  for (let attempt = 0; attempt <= this.retries; attempt++) {
100
102
  try {
101
103
  const response = await this.fetchWithTimeout(url, requestOptions);
@@ -105,6 +107,9 @@ var HttpClient = class {
105
107
  if (error && typeof error === "object" && "status" in error && typeof error.status === "number" && error.status < 500) {
106
108
  throw error;
107
109
  }
110
+ if (!isIdempotent) {
111
+ throw error;
112
+ }
108
113
  if (attempt === this.retries) {
109
114
  break;
110
115
  }
@@ -1261,6 +1266,97 @@ var NewsletterV2Client = class extends BaseV2Client {
1261
1266
  data
1262
1267
  );
1263
1268
  }
1269
+ // --- Lists (get by id) ---
1270
+ async getListById(siteName, id, cachePolicy) {
1271
+ return this.getOne(
1272
+ this.sitePath(siteName, "newsletter", `lists/${encodeURIComponent(id)}`),
1273
+ void 0,
1274
+ cachePolicy
1275
+ );
1276
+ }
1277
+ // --- Subscriptions (admin: lookup / status / delete / bulk) ---
1278
+ async getSubscriptionByEmail(siteName, email, cachePolicy) {
1279
+ return this.getOne(
1280
+ this.sitePath(siteName, "newsletter", "subscriptions/by-email"),
1281
+ { email },
1282
+ cachePolicy
1283
+ );
1284
+ }
1285
+ async updateSubscriptionStatus(siteName, id, data) {
1286
+ return this.post(
1287
+ this.sitePath(siteName, "newsletter", `subscriptions/${encodeURIComponent(id)}/status`),
1288
+ data
1289
+ );
1290
+ }
1291
+ async deleteSubscription(siteName, id) {
1292
+ return this.deleteOne(
1293
+ this.sitePath(siteName, "newsletter", `subscriptions/${encodeURIComponent(id)}`)
1294
+ );
1295
+ }
1296
+ async bulkUpdateSubscriptions(siteName, data) {
1297
+ return this.post(
1298
+ this.sitePath(siteName, "newsletter", "subscriptions/bulk"),
1299
+ data
1300
+ );
1301
+ }
1302
+ // --- Statistics ---
1303
+ async getStatistics(siteName, params, cachePolicy) {
1304
+ return this.getOne(
1305
+ this.sitePath(siteName, "newsletter", "statistics"),
1306
+ params,
1307
+ cachePolicy
1308
+ );
1309
+ }
1310
+ // --- Campaigns (create / update / delete) ---
1311
+ async createCampaign(siteName, data) {
1312
+ return this.post(
1313
+ this.sitePath(siteName, "newsletter", "campaigns"),
1314
+ data
1315
+ );
1316
+ }
1317
+ async updateCampaign(siteName, id, data) {
1318
+ return this.patchOne(
1319
+ this.sitePath(siteName, "newsletter", `campaigns/${encodeURIComponent(id)}`),
1320
+ data
1321
+ );
1322
+ }
1323
+ async deleteCampaign(siteName, id) {
1324
+ return this.deleteOne(
1325
+ this.sitePath(siteName, "newsletter", `campaigns/${encodeURIComponent(id)}`)
1326
+ );
1327
+ }
1328
+ // --- Series ---
1329
+ async listSeries(siteName, params, cachePolicy) {
1330
+ return this.getList(
1331
+ this.sitePath(siteName, "newsletter", "series"),
1332
+ params,
1333
+ cachePolicy
1334
+ );
1335
+ }
1336
+ async getSeries(siteName, id, cachePolicy) {
1337
+ return this.getOne(
1338
+ this.sitePath(siteName, "newsletter", `series/${encodeURIComponent(id)}`),
1339
+ void 0,
1340
+ cachePolicy
1341
+ );
1342
+ }
1343
+ async createSeries(siteName, data) {
1344
+ return this.post(
1345
+ this.sitePath(siteName, "newsletter", "series"),
1346
+ data
1347
+ );
1348
+ }
1349
+ async updateSeries(siteName, id, data) {
1350
+ return this.patchOne(
1351
+ this.sitePath(siteName, "newsletter", `series/${encodeURIComponent(id)}`),
1352
+ data
1353
+ );
1354
+ }
1355
+ async deleteSeries(siteName, id) {
1356
+ return this.deleteOne(
1357
+ this.sitePath(siteName, "newsletter", `series/${encodeURIComponent(id)}`)
1358
+ );
1359
+ }
1264
1360
  };
1265
1361
 
1266
1362
  // src/v2/client/contacts-client.ts
@@ -1449,11 +1545,18 @@ var CreditsV2Client = class extends BaseV2Client {
1449
1545
  // src/v2/client/email-client.ts
1450
1546
  var EmailV2Client = class extends BaseV2Client {
1451
1547
  /**
1452
- * Send a transactional email using the site's configured email provider.
1548
+ * Send a transactional email through the site's email provider.
1549
+ *
1550
+ * Requires a server-side API key — never call this from a browser. Sites
1551
+ * without a configured provider fall back to the platform default with
1552
+ * policy restrictions (owner-only recipients, daily quota).
1453
1553
  *
1454
- * Requires a server-side API key never call this from a browser.
1455
- * The site must have an email provider configured in its settings.
1456
- * At least one of `html` or `text` must be provided.
1554
+ * Provide content one of two ways (mutually exclusive):
1555
+ * - Raw: `subject` plus at least one of `html` / `text`.
1556
+ * - Template: `template_type` (published template for that type) or
1557
+ * `template_id` (published template by ID) plus optional `variables`; the
1558
+ * template is rendered server-side. `subject` is optional here and
1559
+ * overrides the rendered one.
1457
1560
  */
1458
1561
  async send(siteName, params) {
1459
1562
  return this.post(
@@ -1463,6 +1566,66 @@ var EmailV2Client = class extends BaseV2Client {
1463
1566
  }
1464
1567
  };
1465
1568
 
1569
+ // src/v2/client/email-templates-client.ts
1570
+ var EmailTemplatesV2Client = class extends BaseV2Client {
1571
+ path(siteName, suffix = "") {
1572
+ return this.sitePath(siteName, "email", suffix ? `templates/${suffix}` : "templates");
1573
+ }
1574
+ /** List every supported template type with its allowed variables. */
1575
+ async listTypes(siteName, cachePolicy) {
1576
+ return this.getList(
1577
+ this.path(siteName, "types"),
1578
+ void 0,
1579
+ cachePolicy
1580
+ );
1581
+ }
1582
+ /** Get the allowed variables for a single template type. */
1583
+ async getTypeVariables(siteName, templateType, cachePolicy) {
1584
+ return this.getOne(
1585
+ this.path(siteName, `types/${templateType}`),
1586
+ void 0,
1587
+ cachePolicy
1588
+ );
1589
+ }
1590
+ /** List template versions, optionally filtered by type and/or status. */
1591
+ async list(siteName, params, cachePolicy) {
1592
+ return this.getList(this.path(siteName), params, cachePolicy);
1593
+ }
1594
+ /** Get a specific template version by ID (`etpl_…`). */
1595
+ async get(siteName, templateId, cachePolicy) {
1596
+ return this.getOne(
1597
+ this.path(siteName, encodeURIComponent(templateId)),
1598
+ void 0,
1599
+ cachePolicy
1600
+ );
1601
+ }
1602
+ /** Get the currently published version for a template type. */
1603
+ async getPublished(siteName, templateType, cachePolicy) {
1604
+ return this.getOne(
1605
+ this.path(siteName, `published/${templateType}`),
1606
+ void 0,
1607
+ cachePolicy
1608
+ );
1609
+ }
1610
+ /** Create a new template version. */
1611
+ async create(siteName, params) {
1612
+ return this.post(this.path(siteName), params);
1613
+ }
1614
+ /** Clone a template version, optionally overriding fields. */
1615
+ async clone(siteName, templateId, params) {
1616
+ return this.post(
1617
+ this.path(siteName, `${encodeURIComponent(templateId)}/clone`),
1618
+ params ?? {}
1619
+ );
1620
+ }
1621
+ /** Publish a template version (archives the previously published one). */
1622
+ async publish(siteName, templateId) {
1623
+ return this.post(
1624
+ this.path(siteName, `${encodeURIComponent(templateId)}/publish`)
1625
+ );
1626
+ }
1627
+ };
1628
+
1466
1629
  // src/v2/index.ts
1467
1630
  var PerspectApiV2Client = class {
1468
1631
  http;
@@ -1482,6 +1645,7 @@ var PerspectApiV2Client = class {
1482
1645
  subscriptions;
1483
1646
  credits;
1484
1647
  email;
1648
+ emailTemplates;
1485
1649
  constructor(config) {
1486
1650
  const baseUrl = config.baseUrl.replace(/\/+$/, "");
1487
1651
  const v2BaseUrl = baseUrl.endsWith("/api/v2") ? baseUrl : `${baseUrl}/api/v2`;
@@ -1504,6 +1668,7 @@ var PerspectApiV2Client = class {
1504
1668
  this.subscriptions = new SubscriptionsV2Client(this.http, basePath, cache);
1505
1669
  this.credits = new CreditsV2Client(this.http, basePath, cache);
1506
1670
  this.email = new EmailV2Client(this.http, basePath, cache);
1671
+ this.emailTemplates = new EmailTemplatesV2Client(this.http, basePath, cache);
1507
1672
  }
1508
1673
  /** Update the JWT token for authenticated requests. */
1509
1674
  setAuth(jwt) {
@@ -1545,6 +1710,7 @@ export {
1545
1710
  SubscriptionsV2Client,
1546
1711
  CreditsV2Client,
1547
1712
  EmailV2Client,
1713
+ EmailTemplatesV2Client,
1548
1714
  PerspectApiV2Client,
1549
1715
  createPerspectApiV2Client
1550
1716
  };
@@ -1636,22 +1636,71 @@ interface V2NewsletterList extends V2Object {
1636
1636
  created_at: string | null;
1637
1637
  updated_at: string | null;
1638
1638
  }
1639
+ type V2NewsletterCampaignStatus = "draft" | "scheduled" | "sending" | "sent" | "cancelled";
1639
1640
  interface V2NewsletterCampaign extends V2Object {
1640
1641
  object: "newsletter_campaign";
1641
1642
  name: string;
1642
1643
  slug: string | null;
1644
+ slug_prefix?: string | null;
1643
1645
  subject: string;
1644
1646
  preview_text: string | null;
1645
- status: string;
1647
+ markdown_content?: string | null;
1648
+ series_id?: string | null;
1649
+ series_name?: string | null;
1650
+ template_id?: string | null;
1651
+ list_ids?: string[];
1652
+ tags?: string[] | null;
1653
+ notes?: string | null;
1654
+ from_name?: string | null;
1655
+ from_email?: string | null;
1656
+ reply_to_email?: string | null;
1657
+ send_to_all?: boolean;
1658
+ status: V2NewsletterCampaignStatus | string;
1659
+ scheduled_at?: string | null;
1646
1660
  sent_at: string | null;
1647
1661
  completed_at: string | null;
1648
1662
  total_recipients: number;
1649
1663
  sent_count: number;
1664
+ delivered_count?: number;
1650
1665
  opened_count: number;
1651
1666
  clicked_count: number;
1667
+ unsubscribed_count?: number;
1668
+ bounced_count?: number;
1669
+ complained_count?: number;
1670
+ created_at: string | null;
1671
+ updated_at: string | null;
1672
+ }
1673
+ interface V2NewsletterSeries extends V2Object {
1674
+ object: "newsletter_series";
1675
+ name: string;
1676
+ description: string | null;
1677
+ list_ids: string[];
1678
+ from_name: string | null;
1679
+ from_email: string | null;
1680
+ reply_to_email: string | null;
1681
+ subject_prefix: string | null;
1682
+ cadence: "manual" | "daily" | "weekly" | "monthly" | string;
1683
+ timezone: string | null;
1684
+ send_time: string | null;
1685
+ day_of_week: number | null;
1686
+ day_of_month: number | null;
1687
+ status: "active" | "paused" | "archived" | string;
1688
+ last_sent_at: string | null;
1689
+ next_send_at: string | null;
1690
+ tags: string[] | null;
1691
+ notes: string | null;
1652
1692
  created_at: string | null;
1653
1693
  updated_at: string | null;
1654
1694
  }
1695
+ interface V2NewsletterStatistics {
1696
+ object: "newsletter_statistics";
1697
+ total: number;
1698
+ by_status: Record<string, number>;
1699
+ recent_activity: Array<{
1700
+ date: string;
1701
+ count: number;
1702
+ }>;
1703
+ }
1655
1704
  interface V2NewsletterTrackingResponse {
1656
1705
  success: boolean;
1657
1706
  }
@@ -1724,6 +1773,84 @@ interface V2NewsletterImportResult {
1724
1773
  subscription_id: string;
1725
1774
  }>;
1726
1775
  }
1776
+ interface V2NewsletterCampaignCreateParams {
1777
+ campaign_name: string;
1778
+ subject: string;
1779
+ /** Markdown body; rendered to HTML/text server-side. */
1780
+ markdown_content: string;
1781
+ slug?: string;
1782
+ slug_prefix?: string | null;
1783
+ /**
1784
+ * `scheduled` requires a `scheduled_at`, the newsletter plan entitlement, and
1785
+ * the `newsletters.publish` permission on the API key (creating/updating a
1786
+ * draft only needs `newsletters.create`/`newsletters.update`).
1787
+ */
1788
+ status?: "draft" | "scheduled" | "cancelled";
1789
+ /** Local datetime (YYYY-MM-DDTHH:MM[:SS]) in the site/series timezone. */
1790
+ scheduled_at?: string | null;
1791
+ preview_text?: string;
1792
+ from_name?: string;
1793
+ from_email?: string;
1794
+ reply_to_email?: string;
1795
+ /** Newsletter template version ID (`etpl_…`). */
1796
+ template_id?: string | null;
1797
+ /** Series ID (`nsr_…`). */
1798
+ series_id?: string | null;
1799
+ /** Target list IDs (`nll_…`). */
1800
+ list_ids?: string[];
1801
+ tags?: string[];
1802
+ notes?: string;
1803
+ }
1804
+ type V2NewsletterCampaignUpdateParams = Partial<Omit<V2NewsletterCampaignCreateParams, "campaign_name" | "subject" | "markdown_content">> & {
1805
+ campaign_name?: string;
1806
+ subject?: string;
1807
+ markdown_content?: string;
1808
+ };
1809
+ interface V2NewsletterSeriesCreateParams {
1810
+ series_name: string;
1811
+ description?: string;
1812
+ status?: "active" | "paused" | "archived";
1813
+ cadence?: "manual" | "daily" | "weekly" | "monthly";
1814
+ timezone?: string;
1815
+ send_time?: string;
1816
+ day_of_week?: number;
1817
+ day_of_month?: number;
1818
+ next_send_at?: string | null;
1819
+ list_ids?: string[];
1820
+ from_name?: string;
1821
+ from_email?: string;
1822
+ reply_to_email?: string;
1823
+ subject_prefix?: string;
1824
+ tags?: string[];
1825
+ notes?: string;
1826
+ }
1827
+ type V2NewsletterSeriesUpdateParams = Partial<V2NewsletterSeriesCreateParams>;
1828
+ interface V2NewsletterStatisticsParams {
1829
+ start_date?: string;
1830
+ end_date?: string;
1831
+ list_id?: string;
1832
+ }
1833
+ interface V2NewsletterSubscriptionStatusUpdate {
1834
+ status: "confirmed" | "unsubscribed" | "bounced" | "complained";
1835
+ notes?: string;
1836
+ }
1837
+ interface V2NewsletterBulkParams {
1838
+ ids: string[];
1839
+ action: "confirm" | "unsubscribe" | "delete" | "add_to_list" | "remove_from_list";
1840
+ /** Required for add_to_list / remove_from_list. */
1841
+ list_id?: string;
1842
+ }
1843
+ interface V2NewsletterBulkResult {
1844
+ object: "newsletter_bulk_result";
1845
+ succeeded: number;
1846
+ failed: number;
1847
+ /** Per-id failures (id + reason) for the subscriptions that did not apply. */
1848
+ failures: Array<{
1849
+ id: string;
1850
+ error: string;
1851
+ }>;
1852
+ [key: string]: unknown;
1853
+ }
1727
1854
  interface V2ContactSubmission extends V2Object {
1728
1855
  object: "contact_submission";
1729
1856
  name: string | null;
@@ -1875,15 +2002,87 @@ interface V2GrantCreditResult {
1875
2002
  object: "grant_credit_result";
1876
2003
  new_balance_cents: number;
1877
2004
  }
2005
+ 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";
2006
+ type V2EmailTemplateStatus = "draft" | "published" | "archived";
1878
2007
  interface V2EmailSendParams {
1879
2008
  to: string | string[];
1880
- subject: string;
2009
+ /** Required for raw sends; optional (overrides the rendered subject) for template sends. */
2010
+ subject?: string;
1881
2011
  html?: string;
1882
2012
  text?: string;
1883
2013
  from?: string;
1884
2014
  reply_to?: string;
1885
2015
  cc?: string | string[];
1886
2016
  bcc?: string | string[];
2017
+ /**
2018
+ * Template-based send. Provide exactly one of `template_id` (a published
2019
+ * template by ID) or `template_type` (the published template for that type);
2020
+ * the template is rendered server-side with `variables` substituted in.
2021
+ * Mutually exclusive with `html`/`text`.
2022
+ */
2023
+ template_id?: string;
2024
+ template_type?: V2EmailTemplateType;
2025
+ variables?: Record<string, string | number | null>;
2026
+ /**
2027
+ * When true, every placeholder referenced by the template must be present in
2028
+ * `variables` (null counts as provided) — otherwise the API rejects the send
2029
+ * instead of rendering the missing placeholders as empty strings.
2030
+ */
2031
+ strict?: boolean;
2032
+ }
2033
+ interface V2EmailTemplate extends V2Object {
2034
+ object: "email_template";
2035
+ template_type: V2EmailTemplateType;
2036
+ template_name: string;
2037
+ description: string | null;
2038
+ subject_template: string;
2039
+ html_template: string;
2040
+ text_template: string;
2041
+ status: V2EmailTemplateStatus;
2042
+ version: number;
2043
+ variables: string[];
2044
+ created_by: string | null;
2045
+ created_at: string;
2046
+ updated_at: string;
2047
+ published_at: string | null;
2048
+ /** Present on clone responses: the source template ID. */
2049
+ source_template_id?: string;
2050
+ }
2051
+ interface V2EmailTemplateType_Listing {
2052
+ object: "email_template_type";
2053
+ template_type: V2EmailTemplateType;
2054
+ variables: string[];
2055
+ }
2056
+ interface V2EmailTemplateListParams {
2057
+ template_type?: V2EmailTemplateType;
2058
+ status?: V2EmailTemplateStatus;
2059
+ }
2060
+ interface V2EmailTemplateCreateParams {
2061
+ template_type: V2EmailTemplateType;
2062
+ template_name: string;
2063
+ subject_template: string;
2064
+ html_template: string;
2065
+ text_template: string;
2066
+ description?: string;
2067
+ /**
2068
+ * Defaults to "draft". Creating directly into "published" additionally
2069
+ * requires the `templates.publish` permission (and the custom-email plan
2070
+ * entitlement, like all template mutations); otherwise the API returns 403.
2071
+ */
2072
+ status?: "draft" | "published";
2073
+ }
2074
+ interface V2EmailTemplateCloneParams {
2075
+ template_name?: string;
2076
+ subject_template?: string;
2077
+ html_template?: string;
2078
+ text_template?: string;
2079
+ description?: string;
2080
+ /**
2081
+ * Defaults to "draft". Creating directly into "published" additionally
2082
+ * requires the `templates.publish` permission (and the custom-email plan
2083
+ * entitlement, like all template mutations); otherwise the API returns 403.
2084
+ */
2085
+ status?: "draft" | "published";
1887
2086
  }
1888
2087
  interface V2EmailSendResult {
1889
2088
  object: "email";
@@ -2188,6 +2387,22 @@ declare class NewsletterV2Client extends BaseV2Client {
2188
2387
  * processed on the server.
2189
2388
  */
2190
2389
  importSubscriptions(siteName: string, data: V2NewsletterImportRequest): Promise<V2NewsletterImportResult>;
2390
+ getListById(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2NewsletterList>;
2391
+ getSubscriptionByEmail(siteName: string, email: string, cachePolicy?: CachePolicy): Promise<V2NewsletterSubscription>;
2392
+ updateSubscriptionStatus(siteName: string, id: string, data: V2NewsletterSubscriptionStatusUpdate): Promise<V2NewsletterSubscription>;
2393
+ deleteSubscription(siteName: string, id: string): Promise<V2Deleted>;
2394
+ bulkUpdateSubscriptions(siteName: string, data: V2NewsletterBulkParams): Promise<V2NewsletterBulkResult>;
2395
+ getStatistics(siteName: string, params?: V2NewsletterStatisticsParams, cachePolicy?: CachePolicy): Promise<V2NewsletterStatistics>;
2396
+ createCampaign(siteName: string, data: V2NewsletterCampaignCreateParams): Promise<V2NewsletterCampaign>;
2397
+ updateCampaign(siteName: string, id: string, data: V2NewsletterCampaignUpdateParams): Promise<V2NewsletterCampaign>;
2398
+ deleteCampaign(siteName: string, id: string): Promise<V2Deleted>;
2399
+ listSeries(siteName: string, params?: {
2400
+ status?: 'active' | 'paused' | 'archived';
2401
+ }, cachePolicy?: CachePolicy): Promise<V2List<V2NewsletterSeries>>;
2402
+ getSeries(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2NewsletterSeries>;
2403
+ createSeries(siteName: string, data: V2NewsletterSeriesCreateParams): Promise<V2NewsletterSeries>;
2404
+ updateSeries(siteName: string, id: string, data: V2NewsletterSeriesUpdateParams): Promise<V2NewsletterSeries>;
2405
+ deleteSeries(siteName: string, id: string): Promise<V2Deleted>;
2191
2406
  }
2192
2407
 
2193
2408
  /**
@@ -2310,15 +2525,51 @@ declare class CreditsV2Client extends BaseV2Client {
2310
2525
 
2311
2526
  declare class EmailV2Client extends BaseV2Client {
2312
2527
  /**
2313
- * Send a transactional email using the site's configured email provider.
2528
+ * Send a transactional email through the site's email provider.
2314
2529
  *
2315
- * Requires a server-side API key — never call this from a browser.
2316
- * The site must have an email provider configured in its settings.
2317
- * At least one of `html` or `text` must be provided.
2530
+ * Requires a server-side API key — never call this from a browser. Sites
2531
+ * without a configured provider fall back to the platform default with
2532
+ * policy restrictions (owner-only recipients, daily quota).
2533
+ *
2534
+ * Provide content one of two ways (mutually exclusive):
2535
+ * - Raw: `subject` plus at least one of `html` / `text`.
2536
+ * - Template: `template_type` (published template for that type) or
2537
+ * `template_id` (published template by ID) plus optional `variables`; the
2538
+ * template is rendered server-side. `subject` is optional here and
2539
+ * overrides the rendered one.
2318
2540
  */
2319
2541
  send(siteName: string, params: V2EmailSendParams): Promise<V2EmailSendResult>;
2320
2542
  }
2321
2543
 
2544
+ /**
2545
+ * v2 Email Templates Client — versioned CRUD for site email templates.
2546
+ *
2547
+ * Mirrors the email_template_* MCP tools. Templates live under
2548
+ * /sites/:siteName/email/templates. Use `listTypes` / `getTypeVariables` to
2549
+ * discover the allowed substitution variables for each template type before
2550
+ * authoring, then create/clone/publish versions.
2551
+ */
2552
+
2553
+ declare class EmailTemplatesV2Client extends BaseV2Client {
2554
+ private path;
2555
+ /** List every supported template type with its allowed variables. */
2556
+ listTypes(siteName: string, cachePolicy?: CachePolicy): Promise<V2List<V2EmailTemplateType_Listing>>;
2557
+ /** Get the allowed variables for a single template type. */
2558
+ getTypeVariables(siteName: string, templateType: V2EmailTemplateType, cachePolicy?: CachePolicy): Promise<V2EmailTemplateType_Listing>;
2559
+ /** List template versions, optionally filtered by type and/or status. */
2560
+ list(siteName: string, params?: V2EmailTemplateListParams, cachePolicy?: CachePolicy): Promise<V2List<V2EmailTemplate>>;
2561
+ /** Get a specific template version by ID (`etpl_…`). */
2562
+ get(siteName: string, templateId: string, cachePolicy?: CachePolicy): Promise<V2EmailTemplate>;
2563
+ /** Get the currently published version for a template type. */
2564
+ getPublished(siteName: string, templateType: V2EmailTemplateType, cachePolicy?: CachePolicy): Promise<V2EmailTemplate>;
2565
+ /** Create a new template version. */
2566
+ create(siteName: string, params: V2EmailTemplateCreateParams): Promise<V2EmailTemplate>;
2567
+ /** Clone a template version, optionally overriding fields. */
2568
+ clone(siteName: string, templateId: string, params?: V2EmailTemplateCloneParams): Promise<V2EmailTemplate>;
2569
+ /** Publish a template version (archives the previously published one). */
2570
+ publish(siteName: string, templateId: string): Promise<V2EmailTemplate>;
2571
+ }
2572
+
2322
2573
  /**
2323
2574
  * PerspectAPI v2 SDK Client
2324
2575
  *
@@ -2352,6 +2603,7 @@ declare class PerspectApiV2Client {
2352
2603
  readonly subscriptions: SubscriptionsV2Client;
2353
2604
  readonly credits: CreditsV2Client;
2354
2605
  readonly email: EmailV2Client;
2606
+ readonly emailTemplates: EmailTemplatesV2Client;
2355
2607
  constructor(config: PerspectApiV2Config);
2356
2608
  /** Update the JWT token for authenticated requests. */
2357
2609
  setAuth(jwt: string): void;
@@ -2362,4 +2614,4 @@ declare class PerspectApiV2Client {
2362
2614
  }
2363
2615
  declare function createPerspectApiV2Client(config: PerspectApiConfig): PerspectApiV2Client;
2364
2616
 
2365
- export { type NewsletterManagementList as $, type ApiResponse as A, type CreateNewsletterSubscriptionRequest as B, CacheManager as C, type NewsletterConfirmResponse as D, type NewsletterUnsubscribeRequest as E, type NewsletterUnsubscribeResponse as F, type NewsletterPreferences as G, HttpClient as H, type NewsletterList as I, type NewsletterCampaignListResponse as J, type NewsletterCampaignDetail as K, type NewsletterStatusResponse as L, type NewsletterManagementSubscriptionsListResponse as M, type NewsletterSubscribeResponse as N, type Organization as O, type PaginatedResponse as P, type NewsletterManagementSubscription as Q, type NewsletterSubscriptionSyncRequest as R, type Site as S, type NewsletterSubscriptionSyncResponse as T, type User as U, type NewsletterSubscriptionsBulkUpdateRequest as V, type Webhook as W, type NewsletterSubscriptionsBulkUpdateResponse as X, type NewsletterSubscriptionMembershipUpdateRequest as Y, type NewsletterSubscriptionsImportRequest as Z, type NewsletterSubscriptionsImportResponse as _, type CachePolicy as a, type V2ContentListParams as a$, type NewsletterManagementSeries as a0, type NewsletterManagementCampaignListResponse as a1, type NewsletterManagementCampaign as a2, type NewsletterCampaignTestSendRequest as a3, type NewsletterCampaignTestSendResponse as a4, type NewsletterManagementStatsResponse as a5, type NewsletterExportCreateRequest as a6, type NewsletterExportCreateResponse as a7, type RequestOtpRequest as a8, type VerifyOtpRequest as a9, PerspectV2Error as aA, createApiError as aB, PerspectApiError as aC, type CacheConfig as aD, type ApiError as aE, type MediaItem as aF, type CategorySummary as aG, type PaymentGateway as aH, type NewsletterSubscription as aI, type NewsletterCampaignSummary as aJ, type NewsletterManagementListMembership as aK, type NewsletterSubscriptionsBulkAction as aL, type NewsletterSubscriptionsBulkOutcome as aM, type NewsletterSubscriptionImportRowRequest as aN, type NewsletterSubscriptionsImportRowResult as aO, type NewsletterManagementPagination as aP, type SetProfileValueRequest as aQ, type V2Object as aR, type V2List as aS, type V2Deleted as aT, type V2Error as aU, type V2ErrorType as aV, type V2PaginationParams as aW, type V2Media as aX, type V2Content as aY, type V2ContentCreateParams as aZ, type V2ContentUpdateParams as a_, type VerifyOtpResponse as aa, type SiteUser as ab, type SiteUserProfile as ac, type UpdateSiteUserRequest as ad, type SiteUserOrder as ae, type SiteUserSubscription as af, type CancelSubscriptionRequest as ag, type CancelSubscriptionResponse as ah, type CreditBalance as ai, type CreditBalanceWithTransactions as aj, type GrantCreditRequest as ak, type ProductBundleGroup as al, type CreateBundleGroupRequest as am, type BundleCollection as an, type BundleCollectionItemWithProduct as ao, type CreateBundleCollectionRequest as ap, type AddCollectionItemRequest as aq, type BundleCollectionItem as ar, type PerspectApiConfig as as, type CacheAdapter as at, type BlogPost as au, type CheckoutMetadata as av, type CheckoutAddress as aw, type CheckoutTaxRequest as ax, PerspectApiV2Client as ay, createPerspectApiV2Client as az, type CacheInvalidateOptions as b, type ContentType as b$, type V2Product as b0, type V2ProductCreateParams as b1, type V2ProductUpdateParams as b2, type V2ProductListParams as b3, type V2Category as b4, type V2CategoryCreateParams as b5, type V2CategoryUpdateParams as b6, type V2Collection as b7, type V2CollectionItem as b8, type V2CollectionCreateParams as b9, type V2NewsletterSyncResult as bA, type V2NewsletterSubscriptionListMembershipUpdate as bB, type V2NewsletterImportRequest as bC, type V2NewsletterImportResult as bD, type V2ContactSubmission as bE, type V2Organization as bF, type V2Site as bG, type V2ApiKey as bH, type V2WebhookEventType as bI, type V2Webhook as bJ, type V2WebhookCreateParams as bK, type V2WebhookUpdateParams as bL, type V2SiteUserSubscription as bM, type V2SubscriptionPauseParams as bN, type V2SubscriptionCancelParams as bO, type V2SubscriptionChangePlanParams as bP, type V2SubscriptionChargeParams as bQ, type V2SubscriptionChargeResult as bR, type V2CancelSubscriptionResult as bS, type V2CreditTransaction as bT, type V2CreditBalance as bU, type V2GrantCreditParams as bV, type V2GrantCreditResult as bW, type V2EmailSendParams as bX, type V2EmailSendResult as bY, type PaginationParams as bZ, type ContentStatus as b_, type V2CollectionUpdateParams as ba, type V2Order as bb, type V2OrderListParams as bc, type V2OrderLineItemPriceData as bd, type V2OrderLineItem as be, type V2OrderAddress as bf, type V2OrderTaxRequest as bg, type V2OrderCreateParams as bh, type V2OrderFulfillmentUpdate as bi, type V2OrderFulfillmentNotificationLineItem as bj, type V2OrderFulfillmentNotificationParams as bk, type V2OrderFulfillmentNotificationResult as bl, type V2OrderCreateResult as bm, type V2SiteUser as bn, type V2SiteUserUpdateParams as bo, type V2SiteUserMeUpdateParams as bp, type V2SiteUserListParams as bq, type V2SiteUserWithProfile as br, type V2SiteUserProfile as bs, type V2NewsletterSubscription as bt, type V2NewsletterList as bu, type V2NewsletterCampaign as bv, type V2NewsletterTrackingResponse as bw, type V2NewsletterListCreateParams as bx, type V2NewsletterListUpdateParams as by, type V2NewsletterSyncInput as bz, type ContentQueryParams as c, type ProductSkuMediaItem as c0, type ProductSkuOption as c1, type CreatePaymentGatewayRequest as c2, type WebhookEventType as c3, type CheckoutMetadataValue as c4, type CheckoutTaxStrategy as c5, type CheckoutTaxExemptionStatus as c6, type CheckoutTaxCustomerExemptionRequest as c7, type CheckoutTaxBreakdownItem as c8, type CheckoutSessionTax as c9, type SubscriptionCancellationMode as ca, type CreditTransaction as cb, type HttpMethod as cc, type RequestOptions as cd, type PerspectApiV2Config as ce, BaseV2Client as cf, ContentV2Client as cg, ProductsV2Client as ch, CategoriesV2Client as ci, CollectionsV2Client as cj, OrdersV2Client as ck, SiteUsersV2Client as cl, NewsletterV2Client as cm, ContactsV2Client as cn, OrganizationsV2Client as co, SitesV2Client as cp, ApiKeysV2Client as cq, WebhooksV2Client as cr, SubscriptionsV2Client as cs, CreditsV2Client as ct, EmailV2Client as cu, type Content as d, type ContentCategoryResponse as e, type CreateContentRequest as f, type UpdateContentRequest as g, type ApiKey as h, type CreateApiKeyRequest as i, type UpdateApiKeyRequest as j, type CreateOrganizationRequest as k, type CreateSiteRequest as l, type ProductQueryParams as m, type Product as n, type CreateProductRequest as o, type ProductSku as p, type CreateProductSkuRequest as q, type Category as r, type CreateCategoryRequest as s, type CreateWebhookRequest as t, type CreateCheckoutSessionRequest as u, type CheckoutSession as v, type CreateContactRequest as w, type ContactSubmitResponse as x, type ContactStatusResponse as y, type ContactSubmission as z };
2617
+ export { type NewsletterManagementList as $, type ApiResponse as A, type CreateNewsletterSubscriptionRequest as B, CacheManager as C, type NewsletterConfirmResponse as D, type NewsletterUnsubscribeRequest as E, type NewsletterUnsubscribeResponse as F, type NewsletterPreferences as G, HttpClient as H, type NewsletterList as I, type NewsletterCampaignListResponse as J, type NewsletterCampaignDetail as K, type NewsletterStatusResponse as L, type NewsletterManagementSubscriptionsListResponse as M, type NewsletterSubscribeResponse as N, type Organization as O, type PaginatedResponse as P, type NewsletterManagementSubscription as Q, type NewsletterSubscriptionSyncRequest as R, type Site as S, type NewsletterSubscriptionSyncResponse as T, type User as U, type NewsletterSubscriptionsBulkUpdateRequest as V, type Webhook as W, type NewsletterSubscriptionsBulkUpdateResponse as X, type NewsletterSubscriptionMembershipUpdateRequest as Y, type NewsletterSubscriptionsImportRequest as Z, type NewsletterSubscriptionsImportResponse as _, type CachePolicy as a, type V2ContentListParams as a$, type NewsletterManagementSeries as a0, type NewsletterManagementCampaignListResponse as a1, type NewsletterManagementCampaign as a2, type NewsletterCampaignTestSendRequest as a3, type NewsletterCampaignTestSendResponse as a4, type NewsletterManagementStatsResponse as a5, type NewsletterExportCreateRequest as a6, type NewsletterExportCreateResponse as a7, type RequestOtpRequest as a8, type VerifyOtpRequest as a9, PerspectV2Error as aA, createApiError as aB, PerspectApiError as aC, type CacheConfig as aD, type ApiError as aE, type MediaItem as aF, type CategorySummary as aG, type PaymentGateway as aH, type NewsletterSubscription as aI, type NewsletterCampaignSummary as aJ, type NewsletterManagementListMembership as aK, type NewsletterSubscriptionsBulkAction as aL, type NewsletterSubscriptionsBulkOutcome as aM, type NewsletterSubscriptionImportRowRequest as aN, type NewsletterSubscriptionsImportRowResult as aO, type NewsletterManagementPagination as aP, type SetProfileValueRequest as aQ, type V2Object as aR, type V2List as aS, type V2Deleted as aT, type V2Error as aU, type V2ErrorType as aV, type V2PaginationParams as aW, type V2Media as aX, type V2Content as aY, type V2ContentCreateParams as aZ, type V2ContentUpdateParams as a_, type VerifyOtpResponse as aa, type SiteUser as ab, type SiteUserProfile as ac, type UpdateSiteUserRequest as ad, type SiteUserOrder as ae, type SiteUserSubscription as af, type CancelSubscriptionRequest as ag, type CancelSubscriptionResponse as ah, type CreditBalance as ai, type CreditBalanceWithTransactions as aj, type GrantCreditRequest as ak, type ProductBundleGroup as al, type CreateBundleGroupRequest as am, type BundleCollection as an, type BundleCollectionItemWithProduct as ao, type CreateBundleCollectionRequest as ap, type AddCollectionItemRequest as aq, type BundleCollectionItem as ar, type PerspectApiConfig as as, type CacheAdapter as at, type BlogPost as au, type CheckoutMetadata as av, type CheckoutAddress as aw, type CheckoutTaxRequest as ax, PerspectApiV2Client as ay, createPerspectApiV2Client as az, type CacheInvalidateOptions as b, type V2SubscriptionChargeParams as b$, type V2Product as b0, type V2ProductCreateParams as b1, type V2ProductUpdateParams as b2, type V2ProductListParams as b3, type V2Category as b4, type V2CategoryCreateParams as b5, type V2CategoryUpdateParams as b6, type V2Collection as b7, type V2CollectionItem as b8, type V2CollectionCreateParams as b9, type V2NewsletterListCreateParams as bA, type V2NewsletterListUpdateParams as bB, type V2NewsletterSyncInput as bC, type V2NewsletterSyncResult as bD, type V2NewsletterSubscriptionListMembershipUpdate as bE, type V2NewsletterImportRequest as bF, type V2NewsletterImportResult as bG, type V2NewsletterCampaignCreateParams as bH, type V2NewsletterCampaignUpdateParams as bI, type V2NewsletterSeriesCreateParams as bJ, type V2NewsletterSeriesUpdateParams as bK, type V2NewsletterStatisticsParams as bL, type V2NewsletterSubscriptionStatusUpdate as bM, type V2NewsletterBulkParams as bN, type V2NewsletterBulkResult as bO, type V2ContactSubmission as bP, type V2Organization as bQ, type V2Site as bR, type V2ApiKey as bS, type V2WebhookEventType as bT, type V2Webhook as bU, type V2WebhookCreateParams as bV, type V2WebhookUpdateParams as bW, type V2SiteUserSubscription as bX, type V2SubscriptionPauseParams as bY, type V2SubscriptionCancelParams as bZ, type V2SubscriptionChangePlanParams as b_, type V2CollectionUpdateParams as ba, type V2Order as bb, type V2OrderListParams as bc, type V2OrderLineItemPriceData as bd, type V2OrderLineItem as be, type V2OrderAddress as bf, type V2OrderTaxRequest as bg, type V2OrderCreateParams as bh, type V2OrderFulfillmentUpdate as bi, type V2OrderFulfillmentNotificationLineItem as bj, type V2OrderFulfillmentNotificationParams as bk, type V2OrderFulfillmentNotificationResult as bl, type V2OrderCreateResult as bm, type V2SiteUser as bn, type V2SiteUserUpdateParams as bo, type V2SiteUserMeUpdateParams as bp, type V2SiteUserListParams as bq, type V2SiteUserWithProfile as br, type V2SiteUserProfile as bs, type V2NewsletterSubscription as bt, type V2NewsletterList as bu, type V2NewsletterCampaignStatus as bv, type V2NewsletterCampaign as bw, type V2NewsletterSeries as bx, type V2NewsletterStatistics as by, type V2NewsletterTrackingResponse as bz, type ContentQueryParams as c, type V2SubscriptionChargeResult as c0, type V2CancelSubscriptionResult as c1, type V2CreditTransaction as c2, type V2CreditBalance as c3, type V2GrantCreditParams as c4, type V2GrantCreditResult as c5, type V2EmailTemplateType as c6, type V2EmailTemplateStatus as c7, type V2EmailSendParams as c8, type V2EmailTemplate as c9, CategoriesV2Client as cA, CollectionsV2Client as cB, OrdersV2Client as cC, SiteUsersV2Client as cD, NewsletterV2Client as cE, ContactsV2Client as cF, OrganizationsV2Client as cG, SitesV2Client as cH, ApiKeysV2Client as cI, WebhooksV2Client as cJ, SubscriptionsV2Client as cK, CreditsV2Client as cL, EmailV2Client as cM, EmailTemplatesV2Client as cN, type V2EmailTemplateType_Listing as ca, type V2EmailTemplateListParams as cb, type V2EmailTemplateCreateParams as cc, type V2EmailTemplateCloneParams as cd, type V2EmailSendResult as ce, type PaginationParams as cf, type ContentStatus as cg, type ContentType as ch, type ProductSkuMediaItem as ci, type ProductSkuOption as cj, type CreatePaymentGatewayRequest as ck, type WebhookEventType as cl, type CheckoutMetadataValue as cm, type CheckoutTaxStrategy as cn, type CheckoutTaxExemptionStatus as co, type CheckoutTaxCustomerExemptionRequest as cp, type CheckoutTaxBreakdownItem as cq, type CheckoutSessionTax as cr, type SubscriptionCancellationMode as cs, type CreditTransaction as ct, type HttpMethod as cu, type RequestOptions as cv, type PerspectApiV2Config as cw, BaseV2Client as cx, ContentV2Client as cy, ProductsV2Client as cz, type Content as d, type ContentCategoryResponse as e, type CreateContentRequest as f, type UpdateContentRequest as g, type ApiKey as h, type CreateApiKeyRequest as i, type UpdateApiKeyRequest as j, type CreateOrganizationRequest as k, type CreateSiteRequest as l, type ProductQueryParams as m, type Product as n, type CreateProductRequest as o, type ProductSku as p, type CreateProductSkuRequest as q, type Category as r, type CreateCategoryRequest as s, type CreateWebhookRequest as t, type CreateCheckoutSessionRequest as u, type CheckoutSession as v, type CreateContactRequest as w, type ContactSubmitResponse as x, type ContactStatusResponse as y, type ContactSubmission as z };