@usehercules/sdk 1.14.2 → 1.14.4

package/src/client.ts

@@ -11,7 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
-import * as qs from './internal/qs';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
@@ -32,6 +32,16 @@ import {
   Currency,
 } from './resources/commerce/commerce';
 import { Content } from './resources/content/content';
+import {
+  Attachment,
+  Email,
+  EmailGetResponse,
+  EmailListParams,
+  EmailResource,
+  EmailSendParams,
+  EmailSendResponse,
+  EmailsCursorIDPage,
+} from './resources/email/email';
 import {
   PushNotificationEnableResponse,
   PushNotificationIdentifyParams,
@@ -254,8 +264,8 @@ export class Hercules {
     return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
   }
 
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return qs.stringify(query, { arrayFormat: 'comma' });
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -287,12 +297,13 @@ export class Hercules {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -476,7 +487,7 @@ export class Hercules {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -621,9 +632,9 @@ export class Hercules {
       }
     }
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says, but otherwise calculate a default
-    if (!(timeoutMillis && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -750,6 +761,14 @@ export class Hercules {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
@@ -787,6 +806,11 @@ export class Hercules {
    * and SSL status.
    */
   domains: API.Domains = new API.Domains(this);
+  /**
+   * Send transactional emails, send batch emails, and retrieve sent email
+   * history with delivery status tracking.
+   */
+  email: API.EmailResource = new API.EmailResource(this);
   /**
    * Upload, retrieve, and list files and media associated with a website.
    * Upload is a two-step process: first call create to get an upload URL,
@@ -800,6 +824,7 @@ export class Hercules {
 Hercules.Commerce = Commerce;
 Hercules.Content = Content;
 Hercules.Domains = Domains;
+Hercules.EmailResource = EmailResource;
 Hercules.Files = Files;
 Hercules.PushNotifications = PushNotifications;
 
@@ -829,6 +854,17 @@ export declare namespace Hercules {
     type DomainListParams as DomainListParams,
   };
 
+  export {
+    EmailResource as EmailResource,
+    type Attachment as Attachment,
+    type Email as Email,
+    type EmailGetResponse as EmailGetResponse,
+    type EmailSendResponse as EmailSendResponse,
+    type EmailsCursorIDPage as EmailsCursorIDPage,
+    type EmailListParams as EmailListParams,
+    type EmailSendParams as EmailSendParams,
+  };
+
   export {
     Files as Files,
     type File as File,

package/src/internal/utils/query.ts

@@ -0,0 +1,7 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as qs from '../qs/stringify';
+
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return qs.stringify(query, { arrayFormat: 'comma' });
+}

package/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/src/resources/commerce/coupons.ts

@@ -35,11 +35,7 @@ export class Coupons extends APIResource {
    * );
    * ```
    */
-  update(
-    couponID: string,
-    body: CouponUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Coupon> {
+  update(couponID: string, body: CouponUpdateParams, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.patch(path`/v1/commerce/coupons/${couponID}`, { body, ...options });
   }
 

package/src/resources/commerce/customers.ts

@@ -18,7 +18,7 @@ export class Customers extends APIResource {
    * const customer = await client.commerce.customers.create();
    * ```
    */
-  create(body: CustomerCreateParams | null | undefined = {}, options?: RequestOptions): APIPromise<Customer> {
+  create(body: CustomerCreateParams, options?: RequestOptions): APIPromise<Customer> {
     return this._client.post('/v1/commerce/customers', { body, ...options });
   }
 
@@ -33,11 +33,7 @@ export class Customers extends APIResource {
    * );
    * ```
    */
-  update(
-    customerID: string,
-    body: CustomerUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Customer> {
+  update(customerID: string, body: CustomerUpdateParams, options?: RequestOptions): APIPromise<Customer> {
     return this._client.patch(path`/v1/commerce/customers/${customerID}`, { body, ...options });
   }
 
@@ -75,7 +71,7 @@ export class Customers extends APIResource {
    */
   billingPortal(
     customerID: string,
-    body: CustomerBillingPortalParams | null | undefined = {},
+    body: CustomerBillingPortalParams,
     options?: RequestOptions,
   ): APIPromise<CustomerBillingPortalResponse> {
     return this._client.post(path`/v1/commerce/customers/${customerID}/billing_portal`, { body, ...options });

package/src/resources/commerce/features.ts

@@ -33,11 +33,7 @@ export class Features extends APIResource {
    * );
    * ```
    */
-  update(
-    featureID: string,
-    body: FeatureUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Feature> {
+  update(featureID: string, body: FeatureUpdateParams, options?: RequestOptions): APIPromise<Feature> {
     return this._client.patch(path`/v1/commerce/features/${featureID}`, { body, ...options });
   }
 

package/src/resources/commerce/products/products.ts

@@ -61,11 +61,7 @@ export class Products extends APIResource {
    * );
    * ```
    */
-  update(
-    productID: string,
-    body: ProductUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Product> {
+  update(productID: string, body: ProductUpdateParams, options?: RequestOptions): APIPromise<Product> {
     return this._client.patch(path`/v1/commerce/products/${productID}`, { body, ...options });
   }
 

package/src/resources/content/assets.ts

@@ -21,11 +21,7 @@ export class Assets extends APIResource {
    * Updates asset metadata including URL, folder, title, description, and custom
    * metadata.
    */
-  update(
-    assetID: string,
-    body: AssetUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Asset> {
+  update(assetID: string, body: AssetUpdateParams, options?: RequestOptions): APIPromise<Asset> {
     return this._client.patch(path`/v1/content/assets/${assetID}`, { body, ...options });
   }
 

package/src/resources/content/collections/collections.ts

@@ -26,7 +26,7 @@ export class Collections extends APIResource {
    */
   update(
     collectionID: string,
-    body: CollectionUpdateParams | null | undefined = {},
+    body: CollectionUpdateParams,
     options?: RequestOptions,
   ): APIPromise<Collection> {
     return this._client.patch(path`/v1/content/collections/${collectionID}`, { body, ...options });

package/src/resources/content/entries.ts

@@ -20,11 +20,7 @@ export class Entries extends APIResource {
    * fields are modified. Use the version parameter for optimistic locking to prevent
    * concurrent update conflicts.
    */
-  update(
-    entryID: string,
-    body: EntryUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Entry> {
+  update(entryID: string, body: EntryUpdateParams, options?: RequestOptions): APIPromise<Entry> {
     return this._client.patch(path`/v1/content/entries/${entryID}`, { body, ...options });
   }
 
@@ -61,11 +57,7 @@ export class Entries extends APIResource {
    * publishing for a future time. Publishing validates that all required fields have
    * values.
    */
-  publish(
-    entryID: string,
-    body: EntryPublishParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Entry> {
+  publish(entryID: string, body: EntryPublishParams, options?: RequestOptions): APIPromise<Entry> {
     return this._client.post(path`/v1/content/entries/${entryID}/publish`, { body, ...options });
   }
 

package/src/resources/content/locales.ts

@@ -20,11 +20,7 @@ export class Locales extends APIResource {
    * Updates a locale's configuration including name, fallback, default status, and
    * active status.
    */
-  update(
-    localeCode: string,
-    body: LocaleUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Locale> {
+  update(localeCode: string, body: LocaleUpdateParams, options?: RequestOptions): APIPromise<Locale> {
     return this._client.patch(path`/v1/content/locales/${localeCode}`, { body, ...options });
   }
 

package/src/resources/content/releases/releases.ts

@@ -23,11 +23,7 @@ export class Releases extends APIResource {
   /**
    * Updates a release name and description. Only draft releases can be updated.
    */
-  update(
-    releaseID: string,
-    body: ReleaseUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Release> {
+  update(releaseID: string, body: ReleaseUpdateParams, options?: RequestOptions): APIPromise<Release> {
     return this._client.patch(path`/v1/content/releases/${releaseID}`, { body, ...options });
   }
 

package/src/resources/email/email.ts

@@ -0,0 +1,292 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as IdentitiesAPI from './identities';
+import {
+  Identities,
+  IdentitiesCursorIDPage,
+  Identity,
+  IdentityCreateParams,
+  IdentityListParams,
+  IdentityVerifyParams,
+} from './identities';
+import { APIPromise } from '../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Send transactional emails, send batch emails, and retrieve sent email
+ * history with delivery status tracking.
+ */
+export class EmailResource extends APIResource {
+  identities: IdentitiesAPI.Identities = new IdentitiesAPI.Identities(this._client);
+
+  /**
+   * Retrieves a paginated list of sent emails. Returns email metadata including
+   * delivery status.
+   */
+  list(
+    query: EmailListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EmailsCursorIDPage, Email> {
+    return this._client.getAPIList('/v1/email', CursorIDPage<Email>, { query, ...options });
+  }
+
+  /**
+   * Retrieves a single email by its unique identifier.
+   */
+  get(emailID: string, options?: RequestOptions): APIPromise<EmailGetResponse> {
+    return this._client.get(path`/v1/email/${emailID}`, options);
+  }
+
+  /**
+   * Sends a single email. The sender address must be a verified identity for this
+   * website.
+   */
+  send(body: EmailSendParams, options?: RequestOptions): APIPromise<EmailSendResponse> {
+    return this._client.post('/v1/email', { body, ...options });
+  }
+}
+
+export type EmailsCursorIDPage = CursorIDPage<Email>;
+
+/**
+ * A file attachment
+ */
+export interface Attachment {
+  /**
+   * The Base64-encoded content of the attachment. Max 40MB total per email.
+   */
+  content: string;
+
+  /**
+   * The name of the attached file
+   */
+  filename: string;
+
+  /**
+   * The MIME type of the attachment
+   */
+  content_type?: string;
+}
+
+/**
+ * A sent email object
+ */
+export interface Email {
+  /**
+   * Unique identifier for the email
+   */
+  id: string;
+
+  /**
+   * Timestamp when the email was sent
+   */
+  created_at: string;
+
+  /**
+   * Sender email address
+   */
+  from: string;
+
+  /**
+   * Email subject line
+   */
+  subject: string;
+
+  /**
+   * Recipient email addresses
+   */
+  to: Array<string>;
+
+  /**
+   * Blind carbon copy recipients
+   */
+  bcc?: Array<string> | null;
+
+  /**
+   * Carbon copy recipients
+   */
+  cc?: Array<string> | null;
+
+  /**
+   * The most recent event for this email
+   */
+  last_event?: 'sent' | 'delivered' | 'opened' | 'clicked' | 'bounced' | 'complained' | null;
+
+  /**
+   * Reply-to addresses
+   */
+  reply_to?: Array<string> | null;
+}
+
+/**
+ * A sent email object with full body content
+ */
+export interface EmailGetResponse {
+  /**
+   * Unique identifier for the email
+   */
+  id: string;
+
+  /**
+   * Timestamp when the email was sent
+   */
+  created_at: string;
+
+  /**
+   * Sender email address
+   */
+  from: string;
+
+  /**
+   * Email subject line
+   */
+  subject: string;
+
+  /**
+   * Recipient email addresses
+   */
+  to: Array<string>;
+
+  /**
+   * Blind carbon copy recipients
+   */
+  bcc?: Array<string> | null;
+
+  /**
+   * Carbon copy recipients
+   */
+  cc?: Array<string> | null;
+
+  /**
+   * The HTML version of the message body
+   */
+  html?: string | null;
+
+  /**
+   * The most recent event for this email
+   */
+  last_event?: 'sent' | 'delivered' | 'opened' | 'clicked' | 'bounced' | 'complained' | null;
+
+  /**
+   * Reply-to addresses
+   */
+  reply_to?: Array<string> | null;
+
+  /**
+   * The plain text version of the message body
+   */
+  text?: string | null;
+}
+
+/**
+ * Response after sending an email
+ */
+export interface EmailSendResponse {
+  /**
+   * The unique identifier of the sent email
+   */
+  id: string;
+}
+
+export interface EmailListParams extends CursorIDPageParams {}
+
+export interface EmailSendParams {
+  /**
+   * Sender email address. To include a friendly name, use the format 'Your Name
+   * <sender@domain.com>'.
+   */
+  from: string;
+
+  /**
+   * Email subject line
+   */
+  subject: string;
+
+  /**
+   * Recipient email address(es). Maximum 50.
+   */
+  to: string | Array<string>;
+
+  /**
+   * List of file attachments. Total size must not exceed 40MB after Base64 encoding.
+   */
+  attachments?: Array<Attachment>;
+
+  /**
+   * Blind carbon copy recipient(s)
+   */
+  bcc?: string | Array<string>;
+
+  /**
+   * Carbon copy recipient(s)
+   */
+  cc?: string | Array<string>;
+
+  /**
+   * Custom email headers as key-value pairs
+   */
+  headers?: { [key: string]: string };
+
+  /**
+   * The HTML version of the message body
+   */
+  html?: string;
+
+  /**
+   * Reply-to email address(es)
+   */
+  reply_to?: string | Array<string>;
+
+  /**
+   * Custom metadata tags for the email (max 50)
+   */
+  tags?: Array<EmailSendParams.Tag>;
+
+  /**
+   * The plain text version of the message body
+   */
+  text?: string;
+}
+
+export namespace EmailSendParams {
+  /**
+   * A custom metadata tag for the email
+   */
+  export interface Tag {
+    /**
+     * The name of the tag
+     */
+    name: string;
+
+    /**
+     * The value of the tag
+     */
+    value: string;
+  }
+}
+
+EmailResource.Identities = Identities;
+
+export declare namespace EmailResource {
+  export {
+    type Attachment as Attachment,
+    type Email as Email,
+    type EmailGetResponse as EmailGetResponse,
+    type EmailSendResponse as EmailSendResponse,
+    type EmailsCursorIDPage as EmailsCursorIDPage,
+    type EmailListParams as EmailListParams,
+    type EmailSendParams as EmailSendParams,
+  };
+
+  export {
+    Identities as Identities,
+    type Identity as Identity,
+    type IdentitiesCursorIDPage as IdentitiesCursorIDPage,
+    type IdentityCreateParams as IdentityCreateParams,
+    type IdentityListParams as IdentityListParams,
+    type IdentityVerifyParams as IdentityVerifyParams,
+  };
+}