@augno/sdk 0.1.9 → 0.7.1

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

@@ -26,28 +26,28 @@ export class UnitGroups extends APIResource {
   units: UnitGroupsUnitsAPI.Units = new UnitGroupsUnitsAPI.Units(this._client);
 
   /**
-   * Creates a unit group with optional associated units.
+   * Returns a paginated list of unit groups, including system unit groups.
+   *
+   * This endpoint requires the permission: `unit_groups:read`.
    *
    * @example
    * ```ts
-   * const unitGroup = await client.catalog.unitGroups.create({
-   *   base_unit_id: 'un_01966263f74a5a0cae356000a1',
-   *   name: 'Weight Units',
-   *   type: 'mass',
-   *   associated_units: [
-   *     { unit_id: 'un_01966263f74a5a0cae356000a1' },
-   *   ],
-   * });
+   * const listUnitGroup =
+   *   await client.catalog.unitGroups.list();
    * ```
    */
-  create(params: UnitGroupCreateParams, options?: RequestOptions): APIPromise<UnitGroup> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/unit-groups', { query: { include }, body, ...options });
+  list(
+    query: UnitGroupListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ListUnitGroup> {
+    return this._client.get('/v1/catalog/unit-groups', { query, ...options });
   }
 
   /**
    * Returns a unit group by ID.
    *
+   * This endpoint requires the permission: `unit_groups:read`.
+   *
    * @example
    * ```ts
    * const unitGroup = await client.catalog.unitGroups.retrieve(
@@ -63,13 +63,46 @@ export class UnitGroups extends APIResource {
     return this._client.get(path`/v1/catalog/unit-groups/${id}`, { query, ...options });
   }
 
+  /**
+   * Creates a unit group with optional associated units.
+   *
+   * This endpoint requires the permission: `unit_groups:create`.
+   *
+   * @example
+   * ```ts
+   * const unitGroup = await client.catalog.unitGroups.create({
+   *   base_unit_id: 'un_01966263f74a5a0cae356000a1',
+   *   name: 'Weight Units',
+   *   type: 'mass',
+   *   associated_units: [
+   *     {
+   *       unit_id: 'un_01966263f74a5a0cae356000a1',
+   *       discount_percentage: 1,
+   *       discount_fixed: 0,
+   *       customer_portal_visibility: 'visible',
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  create(params: UnitGroupCreateParams, options?: RequestOptions): APIPromise<UnitGroup> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/unit-groups', { query: { include }, body, ...options });
+  }
+
   /**
    * Partially updates a unit group. System unit groups cannot be updated.
    *
+   * This endpoint requires the permission: `unit_groups:update`.
+   *
    * @example
    * ```ts
    * const unitGroup = await client.catalog.unitGroups.update(
    *   'ug_01aad07abb8e41fd392d2d7013',
+   *   {
+   *     base_unit_id: 'un_01966263f74a5a0cae356000a1',
+   *     name: 'Weight Units (Updated)',
+   *   },
    * );
    * ```
    */
@@ -83,24 +116,10 @@ export class UnitGroups extends APIResource {
   }
 
   /**
-   * Returns a paginated list of unit groups, including system unit groups.
+   * Deletes a unit group and all of its associated units. System unit groups cannot
+   * be deleted.
    *
-   * @example
-   * ```ts
-   * const listUnitGroup =
-   *   await client.catalog.unitGroups.list();
-   * ```
-   */
-  list(
-    query: UnitGroupListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ListUnitGroup> {
-    return this._client.get('/v1/catalog/unit-groups', { query, ...options });
-  }
-
-  /**
-   * Deletes a unit group and all associated unit conversions. System unit groups
-   * cannot be deleted.
+   * This endpoint requires the permission: `unit_groups:delete`.
    *
    * @example
    * ```ts
@@ -115,21 +134,25 @@ export class UnitGroups extends APIResource {
 }
 
 /**
- * CreateUnitGroupRequest is a request to create a unit group.
+ * Request to create a unit group.
  */
 export interface CreateUnitGroupRequest {
   /**
-   * Base unit ID.
+   * ID of the unit to designate as the group's reference unit.
    */
   base_unit_id: string;
 
   /**
-   * Display name.
+   * Display name of the unit group.
+   *
+   * Must be unique within the account.
    */
   name: string;
 
   /**
-   * Unit type.
+   * Dimension shared by every unit in this group.
+   *
+   * All associated units must be of this dimension.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
@@ -139,32 +162,36 @@ export interface CreateUnitGroupRequest {
   associated_units?: Array<CreateUnitGroupUnitParam>;
 
   /**
-   * Notes.
+   * Free-form notes about the unit group.
    */
   notes?: string;
 }
 
 /**
- * CreateUnitGroupUnitParam contains parameters for an associated unit.
+ * Parameters for associating a unit with a unit group.
  */
 export interface CreateUnitGroupUnitParam {
   /**
-   * 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;
 }
@@ -210,7 +237,8 @@ export interface ListUnitGroupUnit {
 }
 
 /**
- * UnitGroup is a unit group resource.
+ * Named collection of units sharing one dimension, defining which units products
+ * can be ordered in along with per-unit discounts and customer portal visibility.
  */
 export interface UnitGroup {
   /**
@@ -234,12 +262,14 @@ export interface UnitGroup {
   created_at: string;
 
   /**
-   * Display name.
+   * Display name of the unit group.
+   *
+   * Unique within the account.
    */
   name: string;
 
   /**
-   * Notes.
+   * Free-form notes about the unit group.
    */
   notes: string | null;
 
@@ -254,7 +284,10 @@ export interface UnitGroup {
   owner: APIKeysAPI.Owner | null;
 
   /**
-   * Unit type.
+   * Physical dimension shared by every unit in this group, such as mass, volume, or
+   * currency.
+   *
+   * Only units of this dimension can belong to the group.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
@@ -265,7 +298,8 @@ export interface UnitGroup {
 }
 
 /**
- * UnitGroupUnit is an associated unit within a unit group.
+ * Membership of a unit in a unit group, carrying the discount and customer portal
+ * visibility settings applied when ordering in that unit.
  */
 export interface UnitGroupUnit {
   /**
@@ -279,17 +313,19 @@ export interface UnitGroupUnit {
   created_at: string;
 
   /**
-   * Customer portal visibility.
+   * Whether this 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;
 
@@ -310,64 +346,71 @@ export interface UnitGroupUnit {
 }
 
 /**
- * UpdateUnitGroupRequest is a request to partially update a unit group.
+ * Request to partially update a unit group.
  */
 export interface UpdateUnitGroupRequest {
   /**
-   * Upserts associated units when provided. Existing units not in the list are
-   * preserved.
+   * Associated units to add or update in the group.
+   *
+   * Upserted by unit: a listed unit already in the group has its association
+   * updated, otherwise it is added. Existing units not in the list are preserved.
    */
   associated_units?: Array<CreateUnitGroupUnitParam>;
 
   /**
-   * Base unit ID.
+   * ID of the group's base unit.
    */
   base_unit_id?: string;
 
   /**
-   * Display name.
+   * Display name of the unit group.
+   *
+   * Must be unique within the account.
    */
   name?: string;
 
   /**
-   * Notes. Set to null to clear.
+   * Free-form notes about the unit group.
+   *
+   * Set to `null` to clear.
    */
   notes?: string | null;
 }
 
 export interface UnitGroupDeleteResponse {}
 
-export interface UnitGroupCreateParams {
-  /**
-   * Body param: Base unit ID.
-   */
-  base_unit_id: string;
-
+export interface UnitGroupListParams {
   /**
-   * Body param: Display name.
+   * 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.
    */
-  name: string;
+  cursor?: string;
 
   /**
-   * Body param: Unit type.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
-  type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
+  include?: Array<'owner' | 'owner.account' | 'base_unit' | 'associated_units'>;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Maximum number of results to return in a single page.
    */
-  include?: Array<'owner' | 'owner.account' | 'base_unit' | 'associated_units'>;
+  limit?: number;
 
   /**
-   * Body param: Associated units to create with the group.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
-  associated_units?: Array<CreateUnitGroupUnitParam>;
+  q?: string;
 
   /**
-   * Body param: Notes.
+   * Filter by unit dimension.
    */
-  notes?: string;
+  type?: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 }
 
 export interface UnitGroupRetrieveParams {
@@ -378,61 +421,76 @@ export interface UnitGroupRetrieveParams {
   include?: Array<'owner' | 'owner.account' | 'base_unit' | 'associated_units'>;
 }
 
-export interface UnitGroupUpdateParams {
+export interface UnitGroupCreateParams {
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Body param: ID of the unit to designate as the group's reference unit.
    */
-  include?: Array<'owner' | 'owner.account' | 'base_unit' | 'associated_units'>;
+  base_unit_id: string;
 
   /**
-   * Body param: Upserts associated units when provided. Existing units not in the
-   * list are preserved.
+   * Body param: Display name of the unit group.
+   *
+   * Must be unique within the account.
    */
-  associated_units?: Array<CreateUnitGroupUnitParam>;
+  name: string;
 
   /**
-   * Body param: Base unit ID.
+   * Body param: Dimension shared by every unit in this group.
+   *
+   * All associated units must be of this dimension.
    */
-  base_unit_id?: string;
+  type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
   /**
-   * 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' | 'base_unit' | 'associated_units'>;
 
   /**
-   * Body param: Notes. Set to null to clear.
+   * Body param: Associated units to create with the group.
    */
-  notes?: string | null;
-}
+  associated_units?: Array<CreateUnitGroupUnitParam>;
 
-export interface UnitGroupListParams {
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: Free-form notes about the unit group.
    */
-  cursor?: string;
+  notes?: string;
+}
 
+export interface UnitGroupUpdateParams {
   /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
   include?: Array<'owner' | 'owner.account' | 'base_unit' | 'associated_units'>;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Body param: Associated units to add or update in the group.
+   *
+   * Upserted by unit: a listed unit already in the group has its association
+   * updated, otherwise it is added. Existing units not in the list are preserved.
    */
-  limit?: number;
+  associated_units?: Array<CreateUnitGroupUnitParam>;
 
   /**
-   * Search query used to filter results.
+   * Body param: ID of the group's base unit.
    */
-  q?: string;
+  base_unit_id?: string;
 
   /**
-   * Filter by the unit type.
+   * Body param: Display name of the unit group.
+   *
+   * Must be unique within the account.
    */
-  type?: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
+  name?: string;
+
+  /**
+   * Body param: Free-form notes about the unit group.
+   *
+   * Set to `null` to clear.
+   */
+  notes?: string | null;
 }
 
 UnitGroups.Units = Units;
@@ -447,10 +505,10 @@ export declare namespace UnitGroups {
     type UnitGroupUnit as UnitGroupUnit,
     type UpdateUnitGroupRequest as UpdateUnitGroupRequest,
     type UnitGroupDeleteResponse as UnitGroupDeleteResponse,
-    type UnitGroupCreateParams as UnitGroupCreateParams,
+    type UnitGroupListParams as UnitGroupListParams,
     type UnitGroupRetrieveParams as UnitGroupRetrieveParams,
+    type UnitGroupCreateParams as UnitGroupCreateParams,
     type UnitGroupUpdateParams as UnitGroupUpdateParams,
-    type UnitGroupListParams as UnitGroupListParams,
   };
 
   export {
@@ -458,10 +516,10 @@ export declare namespace UnitGroups {
     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,
   };
 }