@stigg/typescript 0.1.0-alpha.4 → 0.1.0-alpha.7

package/src/internal/qs/utils.ts

@@ -0,0 +1,265 @@
+import { RFC1738 } from './formats';
+import type { DefaultEncoder, Format } from './types';
+import { isArray } from '../utils/values';
+
+export let has = (obj: object, key: PropertyKey): boolean => (
+  (has = (Object as any).hasOwn ?? Function.prototype.call.bind(Object.prototype.hasOwnProperty)),
+  has(obj, key)
+);
+
+const hex_table = /* @__PURE__ */ (() => {
+  const array = [];
+  for (let i = 0; i < 256; ++i) {
+    array.push('%' + ((i < 16 ? '0' : '') + i.toString(16)).toUpperCase());
+  }
+
+  return array;
+})();
+
+function compact_queue<T extends Record<string, any>>(queue: Array<{ obj: T; prop: string }>) {
+  while (queue.length > 1) {
+    const item = queue.pop();
+    if (!item) continue;
+
+    const obj = item.obj[item.prop];
+
+    if (isArray(obj)) {
+      const compacted: unknown[] = [];
+
+      for (let j = 0; j < obj.length; ++j) {
+        if (typeof obj[j] !== 'undefined') {
+          compacted.push(obj[j]);
+        }
+      }
+
+      // @ts-ignore
+      item.obj[item.prop] = compacted;
+    }
+  }
+}
+
+function array_to_object(source: any[], options: { plainObjects: boolean }) {
+  const obj = options && options.plainObjects ? Object.create(null) : {};
+  for (let i = 0; i < source.length; ++i) {
+    if (typeof source[i] !== 'undefined') {
+      obj[i] = source[i];
+    }
+  }
+
+  return obj;
+}
+
+export function merge(
+  target: any,
+  source: any,
+  options: { plainObjects?: boolean; allowPrototypes?: boolean } = {},
+) {
+  if (!source) {
+    return target;
+  }
+
+  if (typeof source !== 'object') {
+    if (isArray(target)) {
+      target.push(source);
+    } else if (target && typeof target === 'object') {
+      if ((options && (options.plainObjects || options.allowPrototypes)) || !has(Object.prototype, source)) {
+        target[source] = true;
+      }
+    } else {
+      return [target, source];
+    }
+
+    return target;
+  }
+
+  if (!target || typeof target !== 'object') {
+    return [target].concat(source);
+  }
+
+  let mergeTarget = target;
+  if (isArray(target) && !isArray(source)) {
+    // @ts-ignore
+    mergeTarget = array_to_object(target, options);
+  }
+
+  if (isArray(target) && isArray(source)) {
+    source.forEach(function (item, i) {
+      if (has(target, i)) {
+        const targetItem = target[i];
+        if (targetItem && typeof targetItem === 'object' && item && typeof item === 'object') {
+          target[i] = merge(targetItem, item, options);
+        } else {
+          target.push(item);
+        }
+      } else {
+        target[i] = item;
+      }
+    });
+    return target;
+  }
+
+  return Object.keys(source).reduce(function (acc, key) {
+    const value = source[key];
+
+    if (has(acc, key)) {
+      acc[key] = merge(acc[key], value, options);
+    } else {
+      acc[key] = value;
+    }
+    return acc;
+  }, mergeTarget);
+}
+
+export function assign_single_source(target: any, source: any) {
+  return Object.keys(source).reduce(function (acc, key) {
+    acc[key] = source[key];
+    return acc;
+  }, target);
+}
+
+export function decode(str: string, _: any, charset: string) {
+  const strWithoutPlus = str.replace(/\+/g, ' ');
+  if (charset === 'iso-8859-1') {
+    // unescape never throws, no try...catch needed:
+    return strWithoutPlus.replace(/%[0-9a-f]{2}/gi, unescape);
+  }
+  // utf-8
+  try {
+    return decodeURIComponent(strWithoutPlus);
+  } catch (e) {
+    return strWithoutPlus;
+  }
+}
+
+const limit = 1024;
+
+export const encode: (
+  str: any,
+  defaultEncoder: DefaultEncoder,
+  charset: string,
+  type: 'key' | 'value',
+  format: Format,
+) => string = (str, _defaultEncoder, charset, _kind, format: Format) => {
+  // This code was originally written by Brian White for the io.js core querystring library.
+  // It has been adapted here for stricter adherence to RFC 3986
+  if (str.length === 0) {
+    return str;
+  }
+
+  let string = str;
+  if (typeof str === 'symbol') {
+    string = Symbol.prototype.toString.call(str);
+  } else if (typeof str !== 'string') {
+    string = String(str);
+  }
+
+  if (charset === 'iso-8859-1') {
+    return escape(string).replace(/%u[0-9a-f]{4}/gi, function ($0) {
+      return '%26%23' + parseInt($0.slice(2), 16) + '%3B';
+    });
+  }
+
+  let out = '';
+  for (let j = 0; j < string.length; j += limit) {
+    const segment = string.length >= limit ? string.slice(j, j + limit) : string;
+    const arr = [];
+
+    for (let i = 0; i < segment.length; ++i) {
+      let c = segment.charCodeAt(i);
+      if (
+        c === 0x2d || // -
+        c === 0x2e || // .
+        c === 0x5f || // _
+        c === 0x7e || // ~
+        (c >= 0x30 && c <= 0x39) || // 0-9
+        (c >= 0x41 && c <= 0x5a) || // a-z
+        (c >= 0x61 && c <= 0x7a) || // A-Z
+        (format === RFC1738 && (c === 0x28 || c === 0x29)) // ( )
+      ) {
+        arr[arr.length] = segment.charAt(i);
+        continue;
+      }
+
+      if (c < 0x80) {
+        arr[arr.length] = hex_table[c];
+        continue;
+      }
+
+      if (c < 0x800) {
+        arr[arr.length] = hex_table[0xc0 | (c >> 6)]! + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      if (c < 0xd800 || c >= 0xe000) {
+        arr[arr.length] =
+          hex_table[0xe0 | (c >> 12)]! + hex_table[0x80 | ((c >> 6) & 0x3f)] + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      i += 1;
+      c = 0x10000 + (((c & 0x3ff) << 10) | (segment.charCodeAt(i) & 0x3ff));
+
+      arr[arr.length] =
+        hex_table[0xf0 | (c >> 18)]! +
+        hex_table[0x80 | ((c >> 12) & 0x3f)] +
+        hex_table[0x80 | ((c >> 6) & 0x3f)] +
+        hex_table[0x80 | (c & 0x3f)];
+    }
+
+    out += arr.join('');
+  }
+
+  return out;
+};
+
+export function compact(value: any) {
+  const queue = [{ obj: { o: value }, prop: 'o' }];
+  const refs = [];
+
+  for (let i = 0; i < queue.length; ++i) {
+    const item = queue[i];
+    // @ts-ignore
+    const obj = item.obj[item.prop];
+
+    const keys = Object.keys(obj);
+    for (let j = 0; j < keys.length; ++j) {
+      const key = keys[j]!;
+      const val = obj[key];
+      if (typeof val === 'object' && val !== null && refs.indexOf(val) === -1) {
+        queue.push({ obj: obj, prop: key });
+        refs.push(val);
+      }
+    }
+  }
+
+  compact_queue(queue);
+
+  return value;
+}
+
+export function is_regexp(obj: any) {
+  return Object.prototype.toString.call(obj) === '[object RegExp]';
+}
+
+export function is_buffer(obj: any) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+
+  return !!(obj.constructor && obj.constructor.isBuffer && obj.constructor.isBuffer(obj));
+}
+
+export function combine(a: any, b: any) {
+  return [].concat(a, b);
+}
+
+export function maybe_map<T>(val: T[], fn: (v: T) => T) {
+  if (isArray(val)) {
+    const mapped = [];
+    for (let i = 0; i < val.length; i += 1) {
+      mapped.push(fn(val[i]!));
+    }
+    return mapped;
+  }
+  return fn(val);
+}

package/src/resources/v1/coupons.ts

@@ -8,21 +8,22 @@ import { path } from '../../internal/utils/path';
 
 export class Coupons extends APIResource {
   /**
-   * Create coupon
+   * Creates a new discount coupon with percentage or fixed amount off, applicable to
+   * customer subscriptions.
    */
   create(body: CouponCreateParams, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.post('/api/v1/coupons', { body, ...options });
   }
 
   /**
-   * Get a single coupon by ID
+   * Retrieves a coupon by its unique identifier.
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<Coupon> {
     return this._client.get(path`/api/v1/coupons/${id}`, options);
   }
 
   /**
-   * Get a list of coupons
+   * Retrieves a paginated list of coupons in the environment.
    */
   list(
     query: CouponListParams | null | undefined = {},
@@ -476,6 +477,11 @@ export interface CouponCreateParams {
    */
   durationInMonths: number | null;
 
+  /**
+   * Metadata associated with the entity
+   */
+  metadata: { [key: string]: string } | null;
+
   /**
    * Name of the coupon
    */
@@ -485,11 +491,6 @@ export interface CouponCreateParams {
    * Percentage discount off the original price
    */
   percentOff: number | null;
-
-  /**
-   * Metadata associated with the entity
-   */
-  additionalMetaData?: unknown;
 }
 
 export namespace CouponCreateParams {
@@ -625,7 +626,54 @@ export namespace CouponCreateParams {
   }
 }
 
-export interface CouponListParams extends MyCursorIDPageParams {}
+export interface CouponListParams extends MyCursorIDPageParams {
+  /**
+   * Filter by entity ID
+   */
+  id?: string;
+
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  createdAt?: CouponListParams.CreatedAt;
+
+  /**
+   * Filter by coupon status. Supports comma-separated values for multiple statuses
+   */
+  status?: string;
+
+  /**
+   * Filter by coupon type (FIXED or PERCENTAGE)
+   */
+  type?: 'FIXED' | 'PERCENTAGE';
+}
+
+export namespace CouponListParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  export interface CreatedAt {
+    /**
+     * Greater than the specified createdAt value
+     */
+    gt?: string;
+
+    /**
+     * Greater than or equal to the specified createdAt value
+     */
+    gte?: string;
+
+    /**
+     * Less than the specified createdAt value
+     */
+    lt?: string;
+
+    /**
+     * Less than or equal to the specified createdAt value
+     */
+    lte?: string;
+  }
+}
 
 export declare namespace Coupons {
   export {

package/src/resources/v1/customers/customers.ts

@@ -22,21 +22,23 @@ export class Customers extends APIResource {
     new PromotionalEntitlementsAPI.PromotionalEntitlements(this._client);
 
   /**
-   * Get a single customer by ID
+   * Retrieves a customer by their unique identifier, including billing information
+   * and subscription status.
    */
   retrieve(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.get(path`/api/v1/customers/${id}`, options);
   }
 
   /**
-   * Update a customer
+   * Updates an existing customer's properties such as name, email, and billing
+   * information.
    */
   update(id: string, body: CustomerUpdateParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.patch(path`/api/v1/customers/${id}`, { body, ...options });
   }
 
   /**
-   * Get a list of customers
+   * Retrieves a paginated list of customers in the environment.
    */
   list(
     query: CustomerListParams | null | undefined = {},
@@ -49,28 +51,46 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Archive customer
+   * Archives a customer, preventing new subscriptions. Optionally cancels existing
+   * subscriptions.
    */
   archive(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post(path`/api/v1/customers/${id}/archive`, options);
   }
 
   /**
-   * Bulk import customers
+   * Imports multiple customers in bulk. Used for migrating customer data from
+   * external systems.
    */
   import(body: CustomerImportParams, options?: RequestOptions): APIPromise<CustomerImportResponse> {
     return this._client.post('/api/v1/customers/import', { body, ...options });
   }
 
   /**
-   * Provision customer
+   * Get a list of customerresources
+   */
+  listResources(
+    id: string,
+    query: CustomerListResourcesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CustomerListResourcesResponsesMyCursorIDPage, CustomerListResourcesResponse> {
+    return this._client.getAPIList(
+      path`/api/v1/customers/${id}/resources`,
+      MyCursorIDPage<CustomerListResourcesResponse>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Creates a new customer and optionally provisions an initial subscription in a
+   * single operation.
    */
   provision(body: CustomerProvisionParams, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post('/api/v1/customers', { body, ...options });
   }
 
   /**
-   * Unarchive customer
+   * Restores an archived customer, allowing them to create new subscriptions again.
    */
   unarchive(id: string, options?: RequestOptions): APIPromise<CustomerResponse> {
     return this._client.post(path`/api/v1/customers/${id}/unarchive`, options);
@@ -79,6 +99,8 @@ export class Customers extends APIResource {
 
 export type CustomerListResponsesMyCursorIDPage = MyCursorIDPage<CustomerListResponse>;
 
+export type CustomerListResourcesResponsesMyCursorIDPage = MyCursorIDPage<CustomerListResourcesResponse>;
+
 /**
  * Response object
  */
@@ -347,6 +369,26 @@ export namespace CustomerImportResponse {
   }
 }
 
+/**
+ * Resource object that belongs to a customer
+ */
+export interface CustomerListResourcesResponse {
+  /**
+   * Resource slug
+   */
+  id: string;
+
+  /**
+   * Timestamp of when the record was created
+   */
+  createdAt: string;
+
+  /**
+   * Timestamp of when the record was last updated
+   */
+  updatedAt: string;
+}
+
 export interface CustomerUpdateParams {
   /**
    * Customer level coupon
@@ -406,7 +448,49 @@ export namespace CustomerUpdateParams {
   }
 }
 
-export interface CustomerListParams extends MyCursorIDPageParams {}
+export interface CustomerListParams extends MyCursorIDPageParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  createdAt?: CustomerListParams.CreatedAt;
+
+  /**
+   * Filter by exact customer email address
+   */
+  email?: string;
+
+  /**
+   * Filter by exact customer name
+   */
+  name?: string;
+}
+
+export namespace CustomerListParams {
+  /**
+   * Filter by creation date using range operators: gt, gte, lt, lte
+   */
+  export interface CreatedAt {
+    /**
+     * Greater than the specified createdAt value
+     */
+    gt?: string;
+
+    /**
+     * Greater than or equal to the specified createdAt value
+     */
+    gte?: string;
+
+    /**
+     * Less than the specified createdAt value
+     */
+    lt?: string;
+
+    /**
+     * Less than or equal to the specified createdAt value
+     */
+    lte?: string;
+  }
+}
 
 export interface CustomerImportParams {
   /**
@@ -449,6 +533,8 @@ export namespace CustomerImportParams {
   }
 }
 
+export interface CustomerListResourcesParams extends MyCursorIDPageParams {}
+
 export interface CustomerProvisionParams {
   /**
    * Customer slug
@@ -556,10 +642,13 @@ export declare namespace Customers {
     type CustomerResponse as CustomerResponse,
     type CustomerListResponse as CustomerListResponse,
     type CustomerImportResponse as CustomerImportResponse,
+    type CustomerListResourcesResponse as CustomerListResourcesResponse,
     type CustomerListResponsesMyCursorIDPage as CustomerListResponsesMyCursorIDPage,
+    type CustomerListResourcesResponsesMyCursorIDPage as CustomerListResourcesResponsesMyCursorIDPage,
     type CustomerUpdateParams as CustomerUpdateParams,
     type CustomerListParams as CustomerListParams,
     type CustomerImportParams as CustomerImportParams,
+    type CustomerListResourcesParams as CustomerListResourcesParams,
     type CustomerProvisionParams as CustomerProvisionParams,
   };
 

package/src/resources/v1/customers/index.ts

@@ -5,11 +5,14 @@ export {
   type CustomerResponse,
   type CustomerListResponse,
   type CustomerImportResponse,
+  type CustomerListResourcesResponse,
   type CustomerUpdateParams,
   type CustomerListParams,
   type CustomerImportParams,
+  type CustomerListResourcesParams,
   type CustomerProvisionParams,
   type CustomerListResponsesMyCursorIDPage,
+  type CustomerListResourcesResponsesMyCursorIDPage,
 } from './customers';
 export { PaymentMethod, type PaymentMethodAttachParams } from './payment-method';
 export {

package/src/resources/v1/customers/payment-method.ts

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class PaymentMethod extends APIResource {
   /**
-   * Attach payment method
+   * Attaches a payment method to a customer for billing. Required for paid
+   * subscriptions when integrated with a billing provider.
    */
   attach(
     id: string,
@@ -19,7 +20,8 @@ export class PaymentMethod extends APIResource {
   }
 
   /**
-   * Detach payment method
+   * Removes the payment method from a customer. Ensure active paid subscriptions
+   * have an alternative payment method.
    */
   detach(id: string, options?: RequestOptions): APIPromise<CustomersAPI.CustomerResponse> {
     return this._client.delete(path`/api/v1/customers/${id}/payment-method`, options);

package/src/resources/v1/customers/promotional-entitlements.ts

@@ -7,7 +7,8 @@ import { path } from '../../../internal/utils/path';
 
 export class PromotionalEntitlements extends APIResource {
   /**
-   * Create a promotional entitlements
+   * Grants promotional entitlements to a customer, providing feature access outside
+   * their subscription. Entitlements can be time-limited or permanent.
    */
   grant(
     customerID: string,
@@ -18,7 +19,8 @@ export class PromotionalEntitlements extends APIResource {
   }
 
   /**
-   * Revoke promotional entitlement
+   * Revokes a previously granted promotional entitlement from a customer for a
+   * specific feature.
    */
   revoke(
     featureID: string,

package/src/resources/v1/events.ts

@@ -6,7 +6,8 @@ import { RequestOptions } from '../../internal/request-options';
 
 export class Events extends APIResource {
   /**
-   * Report usage events
+   * Reports raw usage events for event-based metering. Events are ingested
+   * asynchronously and aggregated into usage totals.
    */
   report(body: EventReportParams, options?: RequestOptions): APIPromise<EventReportResponse> {
     return this._client.post('/api/v1/events', { body, ...options });

package/src/resources/v1/index.ts

@@ -13,13 +13,22 @@ export {
   type CustomerResponse,
   type CustomerListResponse,
   type CustomerImportResponse,
+  type CustomerListResourcesResponse,
   type CustomerUpdateParams,
   type CustomerListParams,
   type CustomerImportParams,
+  type CustomerListResourcesParams,
   type CustomerProvisionParams,
   type CustomerListResponsesMyCursorIDPage,
+  type CustomerListResourcesResponsesMyCursorIDPage,
 } from './customers/index';
 export { Events, type EventReportResponse, type EventReportParams } from './events';
+export {
+  Products,
+  type ProductListProductsResponse,
+  type ProductListProductsParams,
+  type ProductListProductsResponsesMyCursorIDPage,
+} from './products';
 export {
   Subscriptions,
   type Subscription,