@augno/sdk 0.1.9 → 0.7.1

package/src/resources/operations/shipping-terms.ts

@@ -12,26 +12,29 @@ import { path } from '../../internal/utils/path';
  */
 export class ShippingTerms extends APIResource {
   /**
-   * Creates an account-owned shipping term.
+   * Returns a paginated list of shipping terms for the account, including default
+   * system shipping terms.
+   *
+   * This endpoint requires the permission: `shipping_terms:read`.
    *
    * @example
    * ```ts
-   * const shippingTerm =
-   *   await client.operations.shippingTerms.create({
-   *     name: 'Prepaid',
-   *     type: 'carrier_rate_freight',
-   *     free_shipping_service_level_ids: [],
-   *   });
+   * const listShippingTerm =
+   *   await client.operations.shippingTerms.list();
    * ```
    */
-  create(params: ShippingTermCreateParams, options?: RequestOptions): APIPromise<CustomersAPI.ShippingTerm> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/operations/shipping-terms', { query: { include }, body, ...options });
+  list(
+    query: ShippingTermListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ListShippingTerm> {
+    return this._client.get('/v1/operations/shipping-terms', { query, ...options });
   }
 
   /**
    * Returns a shipping term by ID.
    *
+   * This endpoint requires the permission: `shipping_terms:read`.
+   *
    * @example
    * ```ts
    * const shippingTerm =
@@ -49,14 +52,37 @@ export class ShippingTerms extends APIResource {
   }
 
   /**
-   * Partially updates an account-owned shipping term. Default shipping terms cannot
-   * be updated.
+   * Creates an account-owned shipping term.
+   *
+   * This endpoint requires the permission: `shipping_terms:create`.
+   *
+   * @example
+   * ```ts
+   * const shippingTerm =
+   *   await client.operations.shippingTerms.create({
+   *     name: 'Prepaid',
+   *     type: 'carrier_rate_freight',
+   *   });
+   * ```
+   */
+  create(params: ShippingTermCreateParams, options?: RequestOptions): APIPromise<CustomersAPI.ShippingTerm> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/operations/shipping-terms', { query: { include }, body, ...options });
+  }
+
+  /**
+   * Partially updates an account-owned shipping term.
+   *
+   * System-provided default shipping terms cannot be updated.
+   *
+   * This endpoint requires the permission: `shipping_terms:update`.
    *
    * @example
    * ```ts
    * const shippingTerm =
    *   await client.operations.shippingTerms.update(
    *     'shtm_014341ab4bb5bf94d5b6936f86',
+   *     { name: 'Collect' },
    *   );
    * ```
    */
@@ -74,25 +100,11 @@ export class ShippingTerms extends APIResource {
   }
 
   /**
-   * Returns a paginated list of shipping terms for the account, including default
-   * system shipping terms.
+   * Deletes an account-owned shipping term.
    *
-   * @example
-   * ```ts
-   * const listShippingTerm =
-   *   await client.operations.shippingTerms.list();
-   * ```
-   */
-  list(
-    query: ShippingTermListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ListShippingTerm> {
-    return this._client.get('/v1/operations/shipping-terms', { query, ...options });
-  }
-
-  /**
-   * Deletes an account-owned shipping term. Default shipping terms cannot be
-   * deleted.
+   * System-provided default shipping terms cannot be deleted.
+   *
+   * This endpoint requires the permission: `shipping_terms:delete`.
    *
    * @example
    * ```ts
@@ -112,29 +124,35 @@ export class ShippingTerms extends APIResource {
  */
 export interface CreateShippingTermRequest {
   /**
-   * Display name.
+   * Human-readable name for the shipping term, used to identify it when assigning
+   * shipping terms to customers and orders.
    */
   name: string;
 
   /**
-   * Shipping term type.
+   * Freight pricing model applied by this shipping term.
+   *
+   * - `free_freight`: no shipping cost to the buyer.
+   * - `flat_rate_freight`: a fixed shipping cost regardless of order details (see
+   *   `flat_rate`).
+   * - `carrier_rate_freight`: shipping cost is determined by the carrier's quoted
+   *   rate.
    */
   type: 'free_freight' | 'flat_rate_freight' | 'carrier_rate_freight';
 
   /**
-   * QuantityInput represents a value with an associated unit for create/update
-   * requests.
+   * A value with an associated unit, used in create and update requests.
    */
   flat_rate?: CustomersAPI.QuantityInput;
 
   /**
-   * Service level IDs that qualify for free shipping.
+   * IDs of service levels that ship for free under this term (typically once
+   * `minimum_order_value` is met).
    */
   free_shipping_service_level_ids?: Array<string>;
 
   /**
-   * QuantityInput represents a value with an associated unit for create/update
-   * requests.
+   * A value with an associated unit, used in create and update requests.
    */
   minimum_order_value?: CustomersAPI.QuantityInput;
 }
@@ -160,77 +178,80 @@ export interface ListShippingTerm {
 }
 
 /**
- * Request to partially update a shipping term. All fields are optional. Absent
- * fields are left unchanged. Send an explicit JSON null for flat_rate,
- * minimum_order_value, or free_shipping_service_level_ids to clear the existing
- * value.
+ * Request to partially update a shipping term.
+ *
+ * All fields are optional and absent fields are left unchanged. Send an explicit
+ * JSON `null` for `flat_rate`, `minimum_order_value`, or
+ * `free_shipping_service_level_ids` to clear the existing value.
  */
 export interface UpdateShippingTermRequest {
   /**
-   * QuantityInput represents a value with an associated unit for create/update
-   * requests.
+   * A value with an associated unit, used in create and update requests.
    */
   flat_rate?: CustomersAPI.QuantityInput | null;
 
   /**
-   * Service level IDs that qualify for free shipping. Send null to clear.
+   * IDs of service levels that ship for free under this term (typically once
+   * `minimum_order_value` is met).
+   *
+   * Replaces the existing list. Send `null` to clear.
    */
   free_shipping_service_level_ids?: Array<string> | null;
 
   /**
-   * QuantityInput represents a value with an associated unit for create/update
-   * requests.
+   * A value with an associated unit, used in create and update requests.
    */
   minimum_order_value?: CustomersAPI.QuantityInput | null;
 
   /**
-   * Display name.
+   * Human-readable name for the shipping term, used to identify it when assigning
+   * shipping terms to customers and orders.
    */
   name?: string;
 
   /**
-   * Shipping term type.
+   * Freight pricing model applied by this shipping term.
+   *
+   * - `free_freight`: no shipping cost to the buyer.
+   * - `flat_rate_freight`: a fixed shipping cost regardless of order details (see
+   *   `flat_rate`).
+   * - `carrier_rate_freight`: shipping cost is determined by the carrier's quoted
+   *   rate.
    */
   type?: 'free_freight' | 'flat_rate_freight' | 'carrier_rate_freight';
 }
 
 export interface ShippingTermDeleteResponse {}
 
-export interface ShippingTermCreateParams {
-  /**
-   * Body param: Display name.
-   */
-  name: string;
-
+export interface ShippingTermListParams {
   /**
-   * Body param: Shipping term type.
+   * Opaque cursor token identifying where the page of results starts.
+   *
+   * Use the `cursor` value embedded in a previous response's `next_page_url` or
+   * `previous_page_url` to fetch the adjacent page. Omit to start from the first
+   * page.
    */
-  type: 'free_freight' | 'flat_rate_freight' | 'carrier_rate_freight';
+  cursor?: string;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
   include?: Array<
     'owner' | 'owner.account' | 'flat_rate.unit' | 'minimum_order_value.unit' | 'free_shipping_service_levels'
   >;
 
   /**
-   * Body param: QuantityInput represents a value with an associated unit for
-   * create/update requests.
+   * Maximum number of results to return in a single page.
    */
-  flat_rate?: CustomersAPI.QuantityInput;
-
-  /**
-   * Body param: Service level IDs that qualify for free shipping.
-   */
-  free_shipping_service_level_ids?: Array<string>;
+  limit?: number;
 
   /**
-   * Body param: QuantityInput represents a value with an associated unit for
-   * create/update requests.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
-  minimum_order_value?: CustomersAPI.QuantityInput;
+  q?: string;
 }
 
 export interface ShippingTermRetrieveParams {
@@ -243,7 +264,24 @@ export interface ShippingTermRetrieveParams {
   >;
 }
 
-export interface ShippingTermUpdateParams {
+export interface ShippingTermCreateParams {
+  /**
+   * Body param: Human-readable name for the shipping term, used to identify it when
+   * assigning shipping terms to customers and orders.
+   */
+  name: string;
+
+  /**
+   * Body param: Freight pricing model applied by this shipping term.
+   *
+   * - `free_freight`: no shipping cost to the buyer.
+   * - `flat_rate_freight`: a fixed shipping cost regardless of order details (see
+   *   `flat_rate`).
+   * - `carrier_rate_freight`: shipping cost is determined by the carrier's quoted
+   *   rate.
+   */
+  type: 'free_freight' | 'flat_rate_freight' | 'carrier_rate_freight';
+
   /**
    * Query param: Sub-objects to expand in the response. When omitted, sub-objects
    * are returned as `null`.
@@ -253,57 +291,65 @@ export interface ShippingTermUpdateParams {
   >;
 
   /**
-   * Body param: QuantityInput represents a value with an associated unit for
-   * create/update requests.
+   * Body param: A value with an associated unit, used in create and update requests.
    */
-  flat_rate?: CustomersAPI.QuantityInput | null;
+  flat_rate?: CustomersAPI.QuantityInput;
 
   /**
-   * Body param: Service level IDs that qualify for free shipping. Send null to
-   * clear.
+   * Body param: IDs of service levels that ship for free under this term (typically
+   * once `minimum_order_value` is met).
    */
-  free_shipping_service_level_ids?: Array<string> | null;
+  free_shipping_service_level_ids?: Array<string>;
 
   /**
-   * Body param: QuantityInput represents a value with an associated unit for
-   * create/update requests.
+   * Body param: A value with an associated unit, used in create and update requests.
    */
-  minimum_order_value?: CustomersAPI.QuantityInput | null;
+  minimum_order_value?: CustomersAPI.QuantityInput;
+}
 
+export interface ShippingTermUpdateParams {
   /**
-   * Body param: Display name.
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
-  name?: string;
+  include?: Array<
+    'owner' | 'owner.account' | 'flat_rate.unit' | 'minimum_order_value.unit' | 'free_shipping_service_levels'
+  >;
 
   /**
-   * Body param: Shipping term type.
+   * Body param: A value with an associated unit, used in create and update requests.
    */
-  type?: 'free_freight' | 'flat_rate_freight' | 'carrier_rate_freight';
-}
+  flat_rate?: CustomersAPI.QuantityInput | null;
 
-export interface ShippingTermListParams {
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: IDs of service levels that ship for free under this term (typically
+   * once `minimum_order_value` is met).
+   *
+   * Replaces the existing list. Send `null` to clear.
    */
-  cursor?: string;
+  free_shipping_service_level_ids?: Array<string> | null;
 
   /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
+   * Body param: A value with an associated unit, used in create and update requests.
    */
-  include?: Array<
-    'owner' | 'owner.account' | 'flat_rate.unit' | 'minimum_order_value.unit' | 'free_shipping_service_levels'
-  >;
+  minimum_order_value?: CustomersAPI.QuantityInput | null;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Body param: Human-readable name for the shipping term, used to identify it when
+   * assigning shipping terms to customers and orders.
    */
-  limit?: number;
+  name?: string;
 
   /**
-   * Search query used to filter results.
+   * Body param: Freight pricing model applied by this shipping term.
+   *
+   * - `free_freight`: no shipping cost to the buyer.
+   * - `flat_rate_freight`: a fixed shipping cost regardless of order details (see
+   *   `flat_rate`).
+   * - `carrier_rate_freight`: shipping cost is determined by the carrier's quoted
+   *   rate.
    */
-  q?: string;
+  type?: 'free_freight' | 'flat_rate_freight' | 'carrier_rate_freight';
 }
 
 export declare namespace ShippingTerms {
@@ -312,9 +358,9 @@ export declare namespace ShippingTerms {
     type ListShippingTerm as ListShippingTerm,
     type UpdateShippingTermRequest as UpdateShippingTermRequest,
     type ShippingTermDeleteResponse as ShippingTermDeleteResponse,
-    type ShippingTermCreateParams as ShippingTermCreateParams,
+    type ShippingTermListParams as ShippingTermListParams,
     type ShippingTermRetrieveParams as ShippingTermRetrieveParams,
+    type ShippingTermCreateParams as ShippingTermCreateParams,
     type ShippingTermUpdateParams as ShippingTermUpdateParams,
-    type ShippingTermListParams as ShippingTermListParams,
   };
 }