@augno/sdk 0.1.9 → 0.7.1

package/src/resources/catalog/items/items.ts

@@ -17,9 +17,25 @@ import { path } from '../../../internal/utils/path';
 export class Items extends APIResource {
   attributes: AttributesAPI.Attributes = new AttributesAPI.Attributes(this._client);
 
+  /**
+   * Returns a paginated list of items.
+   *
+   * This endpoint requires the permission: `items:read`.
+   *
+   * @example
+   * ```ts
+   * const listItem = await client.catalog.items.list();
+   * ```
+   */
+  list(query: ItemListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListItem> {
+    return this._client.get('/v1/catalog/items', { query, ...options });
+  }
+
   /**
    * Returns an item by ID.
    *
+   * This endpoint requires the permission: `items:read`.
+   *
    * @example
    * ```ts
    * const item = await client.catalog.items.retrieve(
@@ -36,20 +52,35 @@ export class Items extends APIResource {
   }
 
   /**
-   * Returns a paginated list of items.
+   * Returns inventory quantities for an item, including on-hand, reserved,
+   * available-to-promise, and short amounts.
+   *
+   * This endpoint requires the permission: `items:read`.
    *
    * @example
    * ```ts
-   * const listItem = await client.catalog.items.list();
+   * const itemInventory =
+   *   await client.catalog.items.retrieveInventory(
+   *     'it_0131e386ac683e8c29a71f6f1f',
+   *   );
    * ```
    */
-  list(query: ItemListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListItem> {
-    return this._client.get('/v1/catalog/items', { query, ...options });
+  retrieveInventory(
+    id: string,
+    query: ItemRetrieveInventoryParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ItemInventory> {
+    return this._client.get(path`/v1/catalog/items/${id}/inventory`, { query, ...options });
   }
 
   /**
-   * Changes the category of an item. When the category changes, the item's rate
-   * units are updated to the new category's base unit.
+   * Moves an item to a different category.
+   *
+   * The item's rate units (unit value, unit cost, burn rate) and any related
+   * order-point, consumption, and production quantity units are updated to the new
+   * category's base unit. Re-assigning the item's current category is a no-op.
+   *
+   * This endpoint requires the permission: `items:update`.
    *
    * @example
    * ```ts
@@ -70,26 +101,6 @@ export class Items extends APIResource {
       ...options,
     });
   }
-
-  /**
-   * Returns inventory quantities for an item, including on-hand, reserved,
-   * available-to-promise, and short amounts.
-   *
-   * @example
-   * ```ts
-   * const itemInventory =
-   *   await client.catalog.items.retrieveInventory(
-   *     'it_0131e386ac683e8c29a71f6f1f',
-   *   );
-   * ```
-   */
-  retrieveInventory(
-    id: string,
-    query: ItemRetrieveInventoryParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ItemInventory> {
-    return this._client.get(path`/v1/catalog/items/${id}/inventory`, { query, ...options });
-  }
 }
 
 /**
@@ -107,12 +118,14 @@ export interface Item {
   attributes: PropertiesAPI.ListAttribute | null;
 
   /**
-   * Rate resource.
+   * Value expressed as a ratio of two units, such as a price per kilogram or a
+   * throughput per hour.
    */
   burn_rate: Rate | null;
 
   /**
-   * ItemCategory resource.
+   * A grouping of related catalog items that defines the unit group and properties
+   * available to the items within it.
    */
   category: ItemCategory | null;
 
@@ -127,7 +140,7 @@ export interface Item {
   description: string | null;
 
   /**
-   * Notes.
+   * Free-form notes about the item.
    */
   notes: string | null;
 
@@ -137,22 +150,28 @@ export interface Item {
   object: 'item';
 
   /**
-   * Stock keeping unit code.
+   * Stock keeping unit code, unique within the account.
    */
   sku: string;
 
   /**
-   * Item type code.
+   * What kind of item this is.
+   *
+   * - `product`: a finished product.
+   * - `material`: a raw material or component consumed in production.
+   * - `part`: a part used in production.
    */
   type: 'product' | 'material' | 'part';
 
   /**
-   * Rate resource.
+   * Value expressed as a ratio of two units, such as a price per kilogram or a
+   * throughput per hour.
    */
   unit_cost: Rate | null;
 
   /**
-   * Rate resource.
+   * Value expressed as a ratio of two units, such as a price per kilogram or a
+   * throughput per hour.
    */
   unit_value: Rate | null;
 
@@ -163,7 +182,8 @@ export interface Item {
 }
 
 /**
- * ItemCategory resource.
+ * A grouping of related catalog items that defines the unit group and properties
+ * available to the items within it.
  */
 export interface ItemCategory {
   /**
@@ -177,12 +197,12 @@ export interface ItemCategory {
   created_at: string;
 
   /**
-   * Display name.
+   * Display name of the item category.
    */
   name: string;
 
   /**
-   * Notes.
+   * Free-form notes about the item category.
    */
   notes: string | null;
 
@@ -202,12 +222,20 @@ export interface ItemCategory {
   properties: PropertiesAPI.ListProperty | null;
 
   /**
-   * Item category type.
+   * What kind of items this category groups.
+   *
+   * An item can only be assigned to a category whose type matches the item's `type`.
+   *
+   * - `material_category`: groups raw materials and components (items of type
+   *   `material`).
+   * - `product_category`: groups finished products and parts (items of type
+   *   `product` or `part`).
    */
   type: 'material_category' | 'product_category';
 
   /**
-   * 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.
    */
   unit_group: UnitGroupsAPI.UnitGroup | null;
 
@@ -292,13 +320,17 @@ export interface Quantity {
   unit: UnitsAPI.Unit | null;
 
   /**
-   * Decimal value.
+   * Raw decimal value of the quantity, as a string to preserve precision.
+   *
+   * This is the unformatted machine value; see `display_value` for the
+   * human-readable rendering with unit and thousands separators.
    */
   value: string;
 }
 
 /**
- * Rate resource.
+ * Value expressed as a ratio of two units, such as a price per kilogram or a
+ * throughput per hour.
  */
 export interface Rate {
   /**
@@ -337,30 +369,13 @@ export interface Rate {
   updated_at: string;
 
   /**
-   * Rate value as a decimal string.
+   * Decimal value of the rate, as a string to preserve precision.
+   *
+   * Expressed as the amount of the numerator unit per one denominator unit.
    */
   value: string;
 }
 
-export interface ItemRetrieveParams {
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<
-    | 'category'
-    | 'unit_value'
-    | 'unit_cost'
-    | 'burn_rate'
-    | 'attributes'
-    | 'category.unit_group'
-    | 'category.properties'
-    | 'category.unit_group.base_unit'
-    | 'category.unit_group.associated_units'
-    | 'category.unit_group.associated_units.unit'
-  >;
-}
-
 export interface ItemListParams {
   /**
    * Filter by attribute IDs.
@@ -373,7 +388,11 @@ export interface ItemListParams {
   category_ids?: Array<string>;
 
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * 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;
 
@@ -406,7 +425,7 @@ export interface ItemListParams {
   >;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Maximum number of results to return in a single page.
    */
   limit?: number;
 
@@ -417,7 +436,9 @@ export interface ItemListParams {
   product_line_ids?: Array<string>;
 
   /**
-   * Search query used to filter results.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
   q?: string;
 
@@ -427,7 +448,11 @@ export interface ItemListParams {
   start_date?: string;
 
   /**
-   * Which subassemblies to include when listing (default: all).
+   * Restricts results based on where the item is produced in its production flow.
+   *
+   * - `all`: no restriction.
+   * - `initial_only`: only items produced by an initial production step, i.e. a step
+   *   with no upstream steps feeding into it.
    */
   subassembly_filter?: 'all' | 'initial_only';
 
@@ -437,20 +462,15 @@ export interface ItemListParams {
   supplier_id?: string;
 
   /**
-   * Filter by item type codes.
+   * Filter to items of these types (`product`, `material`, `part`).
    */
   types?: Array<string>;
 }
 
-export interface ItemChangeCategoryParams {
-  /**
-   * Path param: Item ID.
-   */
-  id: string;
-
+export interface ItemRetrieveParams {
   /**
-   * 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<
     | 'category'
@@ -474,6 +494,30 @@ export interface ItemRetrieveInventoryParams {
   include?: Array<'on_hand' | 'reserved' | 'available_to_promise' | 'short'>;
 }
 
+export interface ItemChangeCategoryParams {
+  /**
+   * Path param: Item ID.
+   */
+  id: string;
+
+  /**
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
+   */
+  include?: Array<
+    | 'category'
+    | 'unit_value'
+    | 'unit_cost'
+    | 'burn_rate'
+    | 'attributes'
+    | 'category.unit_group'
+    | 'category.properties'
+    | 'category.unit_group.base_unit'
+    | 'category.unit_group.associated_units'
+    | 'category.unit_group.associated_units.unit'
+  >;
+}
+
 Items.Attributes = Attributes;
 
 export declare namespace Items {
@@ -484,10 +528,10 @@ export declare namespace Items {
     type ListItem as ListItem,
     type Quantity as Quantity,
     type Rate as Rate,
-    type ItemRetrieveParams as ItemRetrieveParams,
     type ItemListParams as ItemListParams,
-    type ItemChangeCategoryParams as ItemChangeCategoryParams,
+    type ItemRetrieveParams as ItemRetrieveParams,
     type ItemRetrieveInventoryParams as ItemRetrieveInventoryParams,
+    type ItemChangeCategoryParams as ItemChangeCategoryParams,
   };
 
   export {