@augno/sdk 0.1.9 → 0.7.0

package/src/resources/catalog/unit-groups/units.ts

@@ -11,28 +11,22 @@ import { path } from '../../../internal/utils/path';
  */
 export class Units extends APIResource {
   /**
-   * Creates an associated unit within a unit group.
+   * Returns a list of associated units within a unit group.
    *
    * @example
    * ```ts
-   * const unitGroupUnit =
-   *   await client.catalog.unitGroups.units.create(
+   * const listUnitGroupUnit =
+   *   await client.catalog.unitGroups.units.list(
    *     'ug_01aad07abb8e41fd392d2d7013',
-   *     { unit_id: 'un_01966263f74a5a0cae356000a1' },
    *   );
    * ```
    */
-  create(
+  list(
     unitGroupID: string,
-    params: UnitCreateParams,
+    query: UnitListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<UnitGroupsAPI.UnitGroupUnit> {
-    const { include, ...body } = params;
-    return this._client.post(path`/v1/catalog/unit-groups/${unitGroupID}/units`, {
-      query: { include },
-      body,
-      ...options,
-    });
+  ): APIPromise<UnitGroupsAPI.ListUnitGroupUnit> {
+    return this._client.get(path`/v1/catalog/unit-groups/${unitGroupID}/units`, { query, ...options });
   }
 
   /**
@@ -60,24 +54,29 @@ export class Units extends APIResource {
   }
 
   /**
-   * Partially updates an associated unit within a unit group.
+   * Adds a unit to a unit group. If the unit is already in the group, its existing
+   * association is updated with the provided settings instead.
    *
    * @example
    * ```ts
    * const unitGroupUnit =
-   *   await client.catalog.unitGroups.units.update(
-   *     'un_01966263f74a5a0cae356000a1',
-   *     { unit_group_id: 'ug_01aad07abb8e41fd392d2d7013' },
+   *   await client.catalog.unitGroups.units.create(
+   *     'ug_01aad07abb8e41fd392d2d7013',
+   *     {
+   *       unit_id: 'un_01966263f74a5a0cae356000a1',
+   *       customer_portal_visibility: 'visible',
+   *       discount_percentage: 1,
+   *     },
    *   );
    * ```
    */
-  update(
-    id: string,
-    params: UnitUpdateParams,
+  create(
+    unitGroupID: string,
+    params: UnitCreateParams,
     options?: RequestOptions,
   ): APIPromise<UnitGroupsAPI.UnitGroupUnit> {
-    const { unit_group_id, include, ...body } = params;
-    return this._client.patch(path`/v1/catalog/unit-groups/${unit_group_id}/units/${id}`, {
+    const { include, ...body } = params;
+    return this._client.post(path`/v1/catalog/unit-groups/${unitGroupID}/units`, {
       query: { include },
       body,
       ...options,
@@ -85,26 +84,36 @@ export class Units extends APIResource {
   }
 
   /**
-   * Returns a list of associated units within a unit group.
+   * Partially updates an associated unit within a unit group.
    *
    * @example
    * ```ts
-   * const listUnitGroupUnit =
-   *   await client.catalog.unitGroups.units.list(
-   *     'ug_01aad07abb8e41fd392d2d7013',
+   * const unitGroupUnit =
+   *   await client.catalog.unitGroups.units.update(
+   *     'un_01966263f74a5a0cae356000a1',
+   *     {
+   *       unit_group_id: 'ug_01aad07abb8e41fd392d2d7013',
+   *       discount_percentage: 0.9,
+   *       unit_id: 'un_01966263f74a5a0cae356000a1',
+   *     },
    *   );
    * ```
    */
-  list(
-    unitGroupID: string,
-    query: UnitListParams | null | undefined = {},
+  update(
+    id: string,
+    params: UnitUpdateParams,
     options?: RequestOptions,
-  ): APIPromise<UnitGroupsAPI.ListUnitGroupUnit> {
-    return this._client.get(path`/v1/catalog/unit-groups/${unitGroupID}/units`, { query, ...options });
+  ): APIPromise<UnitGroupsAPI.UnitGroupUnit> {
+    const { unit_group_id, include, ...body } = params;
+    return this._client.patch(path`/v1/catalog/unit-groups/${unit_group_id}/units/${id}`, {
+      query: { include },
+      body,
+      ...options,
+    });
   }
 
   /**
-   * Deletes an associated unit from a unit group.
+   * Removes a unit from a unit group. The unit itself is not deleted.
    *
    * @example
    * ```ts
@@ -121,97 +130,116 @@ export class Units extends APIResource {
 }
 
 /**
- * CreateUnitGroupUnitRequest is a request to create an associated unit within a
- * unit group.
+ * Request to add a unit to a unit group.
  */
 export interface CreateUnitGroupUnitRequest {
   /**
-   * Unit ID.
+   * ID of the unit to associate with the group.
+   *
+   * The unit's dimension must match the group's `type`.
    */
   unit_id: string;
 
   /**
-   * Customer portal visibility.
+   * Whether the unit is shown to customers in the customer portal.
    */
   customer_portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Fixed discount amount.
+   * Flat amount subtracted from the unit's price when an order is placed in this
+   * unit.
    */
   discount_fixed?: number;
 
   /**
-   * Discount percentage.
+   * Percentage discount applied to the unit's price when an order is placed in this
+   * unit (e.g. `10` is a 10% discount).
    */
   discount_percentage?: number;
 }
 
 /**
- * UpdateUnitGroupUnitRequest is a request to update an associated unit.
+ * Request to partially update an associated unit within a unit group.
  */
 export interface UpdateUnitGroupUnitRequest {
   /**
-   * Customer portal visibility.
+   * Whether the unit is shown to customers in the customer portal.
    */
   customer_portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Fixed discount amount.
+   * Flat amount subtracted from the unit's price when an order is placed in this
+   * unit.
    */
   discount_fixed?: number;
 
   /**
-   * Discount percentage.
+   * Percentage discount applied to the unit's price when an order is placed in this
+   * unit (e.g. `10` is a 10% discount).
    */
   discount_percentage?: number;
 
   /**
-   * Unit ID.
+   * ID of the unit this association refers to.
+   *
+   * The unit's dimension must match the group's `type`.
    */
   unit_id?: string;
 }
 
 export interface UnitDeleteResponse {}
 
-export interface UnitCreateParams {
+export interface UnitListParams {
   /**
-   * Body param: Unit ID.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
-  unit_id: string;
+  include?: Array<'unit'>;
+}
+
+export interface UnitRetrieveParams {
+  /**
+   * Path param: Unit group ID.
+   */
+  unit_group_id: string;
 
   /**
    * Query param: Sub-objects to expand in the response. When omitted, sub-objects
    * are returned as `null`.
    */
   include?: Array<'unit'>;
+}
 
+export interface UnitCreateParams {
   /**
-   * Body param: Customer portal visibility.
+   * Body param: ID of the unit to associate with the group.
+   *
+   * The unit's dimension must match the group's `type`.
    */
-  customer_portal_visibility?: 'visible' | 'hidden';
+  unit_id: string;
 
   /**
-   * Body param: Fixed discount amount.
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
-  discount_fixed?: number;
+  include?: Array<'unit'>;
 
   /**
-   * Body param: Discount percentage.
+   * Body param: Whether the unit is shown to customers in the customer portal.
    */
-  discount_percentage?: number;
-}
+  customer_portal_visibility?: 'visible' | 'hidden';
 
-export interface UnitRetrieveParams {
   /**
-   * Path param: Unit group ID.
+   * Body param: Flat amount subtracted from the unit's price when an order is placed
+   * in this unit.
    */
-  unit_group_id: string;
+  discount_fixed?: number;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Body param: Percentage discount applied to the unit's price when an order is
+   * placed in this unit (e.g. `10` is a 10% discount).
    */
-  include?: Array<'unit'>;
+  discount_percentage?: number;
 }
 
 export interface UnitUpdateParams {
@@ -227,34 +255,30 @@ export interface UnitUpdateParams {
   include?: Array<'unit'>;
 
   /**
-   * Body param: Customer portal visibility.
+   * Body param: Whether the unit is shown to customers in the customer portal.
    */
   customer_portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Body param: Fixed discount amount.
+   * Body param: Flat amount subtracted from the unit's price when an order is placed
+   * in this unit.
    */
   discount_fixed?: number;
 
   /**
-   * Body param: Discount percentage.
+   * Body param: Percentage discount applied to the unit's price when an order is
+   * placed in this unit (e.g. `10` is a 10% discount).
    */
   discount_percentage?: number;
 
   /**
-   * Body param: Unit ID.
+   * Body param: ID of the unit this association refers to.
+   *
+   * The unit's dimension must match the group's `type`.
    */
   unit_id?: string;
 }
 
-export interface UnitListParams {
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<'unit'>;
-}
-
 export interface UnitDeleteParams {
   /**
    * Unit group ID.
@@ -267,10 +291,10 @@ export declare namespace Units {
     type CreateUnitGroupUnitRequest as CreateUnitGroupUnitRequest,
     type UpdateUnitGroupUnitRequest as UpdateUnitGroupUnitRequest,
     type UnitDeleteResponse as UnitDeleteResponse,
-    type UnitCreateParams as UnitCreateParams,
+    type UnitListParams as UnitListParams,
     type UnitRetrieveParams as UnitRetrieveParams,
+    type UnitCreateParams as UnitCreateParams,
     type UnitUpdateParams as UnitUpdateParams,
-    type UnitListParams as UnitListParams,
     type UnitDeleteParams as UnitDeleteParams,
   };
 }

package/src/resources/catalog/units.ts

@@ -11,24 +11,16 @@ import { path } from '../../internal/utils/path';
  */
 export class Units extends APIResource {
   /**
-   * Creates an account-owned unit.
+   * Returns a paginated list of units for the current account, including both
+   * account-owned and global system units.
    *
    * @example
    * ```ts
-   * const unit = await client.catalog.units.create({
-   *   abbreviation: 'g',
-   *   name: 'Gram',
-   *   offset_denominator: '1',
-   *   offset_numerator: '0',
-   *   ratio_denominator: '1',
-   *   ratio_numerator: '1',
-   *   type: 'mass',
-   * });
+   * const listUnit = await client.catalog.units.list();
    * ```
    */
-  create(params: UnitCreateParams, options?: RequestOptions): APIPromise<Unit> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/units', { query: { include }, body, ...options });
+  list(query: UnitListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListUnit> {
+    return this._client.get('/v1/catalog/units', { query, ...options });
   }
 
   /**
@@ -49,6 +41,27 @@ export class Units extends APIResource {
     return this._client.get(path`/v1/catalog/units/${id}`, { query, ...options });
   }
 
+  /**
+   * Creates an account-owned unit.
+   *
+   * @example
+   * ```ts
+   * const unit = await client.catalog.units.create({
+   *   abbreviation: 'g',
+   *   name: 'Gram',
+   *   offset_denominator: '1',
+   *   offset_numerator: '0',
+   *   ratio_denominator: '1',
+   *   ratio_numerator: '1',
+   *   type: 'mass',
+   * });
+   * ```
+   */
+  create(params: UnitCreateParams, options?: RequestOptions): APIPromise<Unit> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/units', { query: { include }, body, ...options });
+  }
+
   /**
    * Partially updates an account-owned unit; system units cannot be updated.
    *
@@ -56,6 +69,7 @@ export class Units extends APIResource {
    * ```ts
    * const unit = await client.catalog.units.update(
    *   'un_01966263f74a5a0cae356000a1',
+   *   { abbreviation: 'kg', name: 'Kilogram' },
    * );
    * ```
    */
@@ -68,19 +82,6 @@ export class Units extends APIResource {
     return this._client.patch(path`/v1/catalog/units/${id}`, { query: { include }, body, ...options });
   }
 
-  /**
-   * Returns a paginated list of units for the current account, including both
-   * account-owned and global system units.
-   *
-   * @example
-   * ```ts
-   * const listUnit = await client.catalog.units.list();
-   * ```
-   */
-  list(query: UnitListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListUnit> {
-    return this._client.get('/v1/catalog/units', { query, ...options });
-  }
-
   /**
    * Deletes an account-owned unit. Associated unit group memberships are also
    * removed, and system units cannot be deleted.
@@ -103,11 +104,15 @@ export class Units extends APIResource {
 export interface CreateUnitRequest {
   /**
    * Short abbreviation for the unit (e.g. "g").
+   *
+   * Must be unique within the account.
    */
   abbreviation: string;
 
   /**
    * Display name of the unit (e.g. "Gram").
+   *
+   * Must be unique within the account.
    */
   name: string;
 
@@ -133,7 +138,9 @@ export interface CreateUnitRequest {
   ratio_numerator: string;
 
   /**
-   * Unit dimension code.
+   * Unit dimension (e.g. `mass`, `volume`, `currency`).
+   *
+   * Units can only be converted to other units of the same dimension.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 }
@@ -178,8 +185,10 @@ export interface Unit {
   created_at: string;
 
   /**
-   * Whether this is the base unit for its dimension. Conversion ratios are relative
-   * to this unit.
+   * Whether this is the base unit for its dimension.
+   *
+   * Conversion ratios are relative to this unit. Base units are platform-defined;
+   * account-created units always have this set to `false`.
    */
   is_base_unit: boolean;
 
@@ -194,13 +203,16 @@ export interface Unit {
   object: 'unit';
 
   /**
-   * Conversion offset denominator. Typically 1. Cannot be zero.
+   * Conversion offset denominator.
+   *
+   * Typically 1. Cannot be zero.
    */
   offset_denominator: string;
 
   /**
-   * Conversion offset numerator, used for temperature-like conversions. Zero for
-   * most unit types.
+   * Conversion offset numerator, used for temperature-like conversions.
+   *
+   * Zero for most unit types.
    */
   offset_numerator: string;
 
@@ -211,6 +223,7 @@ export interface Unit {
 
   /**
    * Conversion ratio denominator relative to the base unit in the same dimension.
+   *
    * Cannot be zero.
    */
   ratio_denominator: string;
@@ -221,7 +234,11 @@ export interface Unit {
   ratio_numerator: string;
 
   /**
-   * Unit dimension.
+   * Physical dimension the unit measures, such as mass, volume, or currency.
+   *
+   * A unit can only be converted to another unit of the same dimension. The
+   * `quantity` dimension is for discrete countable items rather than a physical
+   * measure.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
@@ -237,11 +254,15 @@ export interface Unit {
 export interface UpdateUnitRequest {
   /**
    * Short abbreviation for the unit.
+   *
+   * Must be unique within the account.
    */
   abbreviation?: string;
 
   /**
    * Display name of the unit.
+   *
+   * Must be unique within the account.
    */
   name?: string;
 
@@ -268,14 +289,65 @@ export interface UpdateUnitRequest {
 
 export interface UnitDeleteResponse {}
 
+export interface UnitListParams {
+  /**
+   * 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.
+   */
+  cursor?: string;
+
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'owner' | 'owner.account'>;
+
+  /**
+   * Maximum number of results to return in a single page.
+   */
+  limit?: number;
+
+  /**
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
+   */
+  q?: string;
+
+  /**
+   * Filter by unit dimension (e.g. `mass`).
+   */
+  type?: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
+
+  /**
+   * Return only units that belong to at least one of the given unit groups.
+   */
+  unit_group_ids?: Array<string>;
+}
+
+export interface UnitRetrieveParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'owner' | 'owner.account'>;
+}
+
 export interface UnitCreateParams {
   /**
    * Body param: Short abbreviation for the unit (e.g. "g").
+   *
+   * Must be unique within the account.
    */
   abbreviation: string;
 
   /**
    * Body param: Display name of the unit (e.g. "Gram").
+   *
+   * Must be unique within the account.
    */
   name: string;
 
@@ -303,7 +375,9 @@ export interface UnitCreateParams {
   ratio_numerator: string;
 
   /**
-   * Body param: Unit dimension code.
+   * Body param: Unit dimension (e.g. `mass`, `volume`, `currency`).
+   *
+   * Units can only be converted to other units of the same dimension.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
@@ -314,14 +388,6 @@ export interface UnitCreateParams {
   include?: Array<'owner' | 'owner.account'>;
 }
 
-export interface UnitRetrieveParams {
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<'owner' | 'owner.account'>;
-}
-
 export interface UnitUpdateParams {
   /**
    * Query param: Sub-objects to expand in the response. When omitted, sub-objects
@@ -331,11 +397,15 @@ export interface UnitUpdateParams {
 
   /**
    * Body param: Short abbreviation for the unit.
+   *
+   * Must be unique within the account.
    */
   abbreviation?: string;
 
   /**
    * Body param: Display name of the unit.
+   *
+   * Must be unique within the account.
    */
   name?: string;
 
@@ -361,39 +431,6 @@ export interface UnitUpdateParams {
   ratio_numerator?: string;
 }
 
-export interface UnitListParams {
-  /**
-   * Cursor token used to retrieve the next or previous page of results.
-   */
-  cursor?: string;
-
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<'owner' | 'owner.account'>;
-
-  /**
-   * Maximum number of results per page (default: 100, max: 1000).
-   */
-  limit?: number;
-
-  /**
-   * Search query used to filter results.
-   */
-  q?: string;
-
-  /**
-   * Filter by unit dimension code.
-   */
-  type?: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
-
-  /**
-   * Filter by unit group membership.
-   */
-  unit_group_ids?: Array<string>;
-}
-
 export declare namespace Units {
   export {
     type CreateUnitRequest as CreateUnitRequest,
@@ -401,9 +438,9 @@ export declare namespace Units {
     type Unit as Unit,
     type UpdateUnitRequest as UpdateUnitRequest,
     type UnitDeleteResponse as UnitDeleteResponse,
-    type UnitCreateParams as UnitCreateParams,
+    type UnitListParams as UnitListParams,
     type UnitRetrieveParams as UnitRetrieveParams,
+    type UnitCreateParams as UnitCreateParams,
     type UnitUpdateParams as UnitUpdateParams,
-    type UnitListParams as UnitListParams,
   };
 }