@augno/sdk 0.1.9 → 0.7.1

package/src/resources/catalog/materials.ts

@@ -12,24 +12,29 @@ import { path } from '../../internal/utils/path';
  */
 export class Materials extends APIResource {
   /**
-   * Creates a material.
+   * Returns a paginated list of materials.
+   *
+   * This endpoint requires the permissions: `materials:read`, `customers:read`,
+   * `suppliers:read`.
    *
    * @example
    * ```ts
-   * const material = await client.catalog.materials.create({
-   *   category_id: 'ic_01ae7bd7bfd21ca0ab81e1357e',
-   *   sku: 'MAT-001',
-   * });
+   * const listMaterial = await client.catalog.materials.list();
    * ```
    */
-  create(params: MaterialCreateParams, options?: RequestOptions): APIPromise<Material> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/materials', { query: { include }, body, ...options });
+  list(
+    query: MaterialListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ListMaterial> {
+    return this._client.get('/v1/catalog/materials', { query, ...options });
   }
 
   /**
    * Returns a material by ID.
    *
+   * This endpoint requires the permissions: `materials:read`, `customers:read`,
+   * `suppliers:read`.
+   *
    * @example
    * ```ts
    * const material = await client.catalog.materials.retrieve(
@@ -45,13 +50,41 @@ export class Materials extends APIResource {
     return this._client.get(path`/v1/catalog/materials/${id}`, { query, ...options });
   }
 
+  /**
+   * Creates a material with the specified SKU and category.
+   *
+   * Inventory tracking for the new material starts at a zero on-hand quantity in the
+   * category's base unit.
+   *
+   * This endpoint requires the permissions: `materials:create`, `customers:update`,
+   * `suppliers:update`.
+   *
+   * @example
+   * ```ts
+   * const material = await client.catalog.materials.create({
+   *   category_id: 'ic_01ae7bd7bfd21ca0ab81e1357e',
+   *   sku: 'MAT-001',
+   * });
+   * ```
+   */
+  create(params: MaterialCreateParams, options?: RequestOptions): APIPromise<Material> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/materials', { query: { include }, body, ...options });
+  }
+
   /**
    * Partially updates a material.
    *
+   * Fields not provided retain their current values.
+   *
+   * This endpoint requires the permissions: `materials:update`, `customers:update`,
+   * `suppliers:update`.
+   *
    * @example
    * ```ts
    * const material = await client.catalog.materials.update(
    *   'ml_014613b8f7959a091d8cc0cef4',
+   *   { sku: 'MAT-001-UPDATED' },
    * );
    * ```
    */
@@ -65,22 +98,14 @@ export class Materials extends APIResource {
   }
 
   /**
-   * Returns a paginated list of materials.
+   * Deletes a material.
    *
-   * @example
-   * ```ts
-   * const listMaterial = await client.catalog.materials.list();
-   * ```
-   */
-  list(
-    query: MaterialListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ListMaterial> {
-    return this._client.get('/v1/catalog/materials', { query, ...options });
-  }
-
-  /**
-   * Deletes a material by ID.
+   * This is a soft delete: the material is marked deleted and no longer returned by
+   * other endpoints, but the record is retained. Deleting an already-deleted
+   * material returns an error.
+   *
+   * This endpoint requires the permissions: `materials:delete`, `customers:update`,
+   * `suppliers:update`.
    *
    * @example
    * ```ts
@@ -99,47 +124,55 @@ export class Materials extends APIResource {
  */
 export interface CreateMaterialRequest {
   /**
-   * Category ID.
+   * ID of the item category to place the material in.
+   *
+   * The category's unit group determines the base unit used for the material's rates
+   * (`unit_value`, `unit_cost`, `burn_rate`).
    */
   category_id: string;
 
   /**
-   * SKU code.
+   * Stock keeping unit code for the material.
+   *
+   * Must be unique within the account; creating a material with a SKU already used
+   * by another item fails with a conflict error.
    */
   sku: string;
 
   /**
-   * Attribute IDs to connect to the material at creation time.
+   * IDs of existing attributes to link to the material at creation time.
    */
   attribute_ids?: Array<string>;
 
   /**
-   * Description.
+   * Free-form description of the material.
    */
   description?: string;
 
   /**
-   * QuantityInputRequest is a quantity value and unit.
+   * A quantity, given as a decimal value and the unit it is measured in.
    */
   lead_time?: QuantityInputRequest;
 
   /**
-   * Notes.
+   * Free-form notes about the material.
    */
   notes?: string;
 
   /**
-   * QuantityInputRequest is a quantity value and unit.
+   * A quantity, given as a decimal value and the unit it is measured in.
    */
   order_point?: QuantityInputRequest;
 
   /**
-   * RateInput represents the input for creating or updating a rate.
+   * A rate value with its numerator and denominator units, used in create and update
+   * requests.
    */
   unit_cost?: RateInput;
 
   /**
-   * RateInput represents the input for creating or updating a rate.
+   * A rate value with its numerator and denominator units, used in create and update
+   * requests.
    */
   unit_price?: RateInput;
 }
@@ -165,7 +198,12 @@ export interface ListMaterial {
 }
 
 /**
- * Material with order point and lead time.
+ * A material in the account's catalog: a raw material or component consumed in
+ * production.
+ *
+ * Material-level data such as the SKU, description, category, pricing, and
+ * attributes lives on the underlying `item`; the material record adds the
+ * reordering fields `order_point` and `lead_time`.
  */
 export interface Material {
   /**
@@ -205,36 +243,38 @@ export interface Material {
 }
 
 /**
- * QuantityInputRequest is a quantity value and unit.
+ * A quantity, given as a decimal value and the unit it is measured in.
  */
 export interface QuantityInputRequest {
   /**
-   * Unit ID.
+   * ID of the unit the value is expressed in.
    */
   unit_id: string;
 
   /**
-   * Quantity value.
+   * Decimal value of the quantity.
    */
   value: string;
 }
 
 /**
- * RateInput represents the input for creating or updating a rate.
+ * A rate value with its numerator and denominator units, used in create and update
+ * requests.
  */
 export interface RateInput {
   /**
-   * Denominator unit ID.
+   * ID of the unit for the rate's denominator (the per-unit basis).
    */
   denominator_unit_id: string;
 
   /**
-   * Numerator unit ID.
+   * ID of the unit for the rate's numerator (e.g. the currency of a price).
    */
   numerator_unit_id: string;
 
   /**
-   * Decimal value of the rate.
+   * Decimal value of the rate, expressed as the amount of the numerator unit per one
+   * denominator unit.
    */
   value: string;
 }
@@ -244,50 +284,68 @@ export interface RateInput {
  */
 export interface UpdateMaterialRequest {
   /**
-   * Description.
+   * New description for the material.
    */
   description?: string;
 
   /**
-   * QuantityInputRequest is a quantity value and unit.
+   * A quantity, given as a decimal value and the unit it is measured in.
    */
   lead_time?: QuantityInputRequest;
 
   /**
-   * Notes.
+   * New notes for the material.
    */
   notes?: string;
 
   /**
-   * QuantityInputRequest is a quantity value and unit.
+   * A quantity, given as a decimal value and the unit it is measured in.
    */
   order_point?: QuantityInputRequest;
 
   /**
-   * SKU code.
+   * New stock keeping unit code for the material.
+   *
+   * Must remain unique within the account; a conflict error is returned if another
+   * item already uses it.
    */
   sku?: string;
 
   /**
-   * RateInput represents the input for creating or updating a rate.
+   * A rate value with its numerator and denominator units, used in create and update
+   * requests.
    */
   unit_cost?: RateInput;
 }
 
-export interface MaterialCreateParams {
+export interface MaterialListParams {
   /**
-   * Body param: Category ID.
+   * Filter by attribute IDs.
    */
-  category_id: string;
+  attribute_ids?: Array<string>;
 
   /**
-   * Body param: SKU code.
+   * Filter by category IDs.
    */
-  sku: string;
+  category_ids?: Array<string>;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * 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;
+
+  /**
+   * Filter to materials created on or before this date.
+   */
+  end_date?: string;
+
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
   include?: Array<
     | 'item'
@@ -301,39 +359,21 @@ export interface MaterialCreateParams {
   >;
 
   /**
-   * Body param: Attribute IDs to connect to the material at creation time.
-   */
-  attribute_ids?: Array<string>;
-
-  /**
-   * Body param: Description.
-   */
-  description?: string;
-
-  /**
-   * Body param: QuantityInputRequest is a quantity value and unit.
-   */
-  lead_time?: QuantityInputRequest;
-
-  /**
-   * Body param: Notes.
+   * Maximum number of results to return in a single page.
    */
-  notes?: string;
-
-  /**
-   * Body param: QuantityInputRequest is a quantity value and unit.
-   */
-  order_point?: QuantityInputRequest;
+  limit?: number;
 
   /**
-   * Body param: RateInput represents the input for creating or updating a rate.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
-  unit_cost?: RateInput;
+  q?: string;
 
   /**
-   * Body param: RateInput represents the input for creating or updating a rate.
+   * Filter to materials created on or after this date.
    */
-  unit_price?: RateInput;
+  start_date?: string;
 }
 
 export interface MaterialRetrieveParams {
@@ -353,7 +393,23 @@ export interface MaterialRetrieveParams {
   >;
 }
 
-export interface MaterialUpdateParams {
+export interface MaterialCreateParams {
+  /**
+   * Body param: ID of the item category to place the material in.
+   *
+   * The category's unit group determines the base unit used for the material's rates
+   * (`unit_value`, `unit_cost`, `burn_rate`).
+   */
+  category_id: string;
+
+  /**
+   * Body param: Stock keeping unit code for the material.
+   *
+   * Must be unique within the account; creating a material with a SKU already used
+   * by another item fails with a conflict error.
+   */
+  sku: string;
+
   /**
    * Query param: Sub-objects to expand in the response. When omitted, sub-objects
    * are returned as `null`.
@@ -370,60 +426,47 @@ export interface MaterialUpdateParams {
   >;
 
   /**
-   * Body param: Description.
+   * Body param: IDs of existing attributes to link to the material at creation time.
+   */
+  attribute_ids?: Array<string>;
+
+  /**
+   * Body param: Free-form description of the material.
    */
   description?: string;
 
   /**
-   * Body param: QuantityInputRequest is a quantity value and unit.
+   * Body param: A quantity, given as a decimal value and the unit it is measured in.
    */
   lead_time?: QuantityInputRequest;
 
   /**
-   * Body param: Notes.
+   * Body param: Free-form notes about the material.
    */
   notes?: string;
 
   /**
-   * Body param: QuantityInputRequest is a quantity value and unit.
+   * Body param: A quantity, given as a decimal value and the unit it is measured in.
    */
   order_point?: QuantityInputRequest;
 
   /**
-   * Body param: SKU code.
-   */
-  sku?: string;
-
-  /**
-   * Body param: RateInput represents the input for creating or updating a rate.
+   * Body param: A rate value with its numerator and denominator units, used in
+   * create and update requests.
    */
   unit_cost?: RateInput;
-}
-
-export interface MaterialListParams {
-  /**
-   * Filter by attribute IDs.
-   */
-  attribute_ids?: Array<string>;
 
   /**
-   * Filter by category IDs.
-   */
-  category_ids?: Array<string>;
-
-  /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: A rate value with its numerator and denominator units, used in
+   * create and update requests.
    */
-  cursor?: string;
-
-  /**
-   * Filter to materials created on or before this date.
-   */
-  end_date?: string;
+  unit_price?: RateInput;
+}
 
+export interface MaterialUpdateParams {
   /**
-   * 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<
     | 'item'
@@ -437,19 +480,38 @@ export interface MaterialListParams {
   >;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Body param: New description for the material.
    */
-  limit?: number;
+  description?: string;
 
   /**
-   * Search query used to filter results.
+   * Body param: A quantity, given as a decimal value and the unit it is measured in.
    */
-  q?: string;
+  lead_time?: QuantityInputRequest;
 
   /**
-   * Filter to materials created on or after this date.
+   * Body param: New notes for the material.
    */
-  start_date?: string;
+  notes?: string;
+
+  /**
+   * Body param: A quantity, given as a decimal value and the unit it is measured in.
+   */
+  order_point?: QuantityInputRequest;
+
+  /**
+   * Body param: New stock keeping unit code for the material.
+   *
+   * Must remain unique within the account; a conflict error is returned if another
+   * item already uses it.
+   */
+  sku?: string;
+
+  /**
+   * Body param: A rate value with its numerator and denominator units, used in
+   * create and update requests.
+   */
+  unit_cost?: RateInput;
 }
 
 export declare namespace Materials {
@@ -460,9 +522,9 @@ export declare namespace Materials {
     type QuantityInputRequest as QuantityInputRequest,
     type RateInput as RateInput,
     type UpdateMaterialRequest as UpdateMaterialRequest,
-    type MaterialCreateParams as MaterialCreateParams,
+    type MaterialListParams as MaterialListParams,
     type MaterialRetrieveParams as MaterialRetrieveParams,
+    type MaterialCreateParams as MaterialCreateParams,
     type MaterialUpdateParams as MaterialUpdateParams,
-    type MaterialListParams as MaterialListParams,
   };
 }