@augno/sdk 0.1.9 → 0.7.1

package/src/resources/catalog/parts.ts

@@ -13,24 +13,26 @@ import { path } from '../../internal/utils/path';
  */
 export class Parts extends APIResource {
   /**
-   * Creates a part with the specified SKU and category.
+   * Returns a paginated list of parts for the current account.
+   *
+   * This endpoint requires the permissions: `parts:read`, `customers:read`,
+   * `suppliers:read`.
    *
    * @example
    * ```ts
-   * const part = await client.catalog.parts.create({
-   *   category_id: 'ic_01ae7bd7bfd21ca0ab81e1357e',
-   *   sku: 'BRG-6204-2RS',
-   * });
+   * const listPart = await client.catalog.parts.list();
    * ```
    */
-  create(params: PartCreateParams, options?: RequestOptions): APIPromise<Part> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/parts', { query: { include }, body, ...options });
+  list(query: PartListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListPart> {
+    return this._client.get('/v1/catalog/parts', { query, ...options });
   }
 
   /**
    * Returns a part by ID.
    *
+   * This endpoint requires the permissions: `parts:read`, `customers:read`,
+   * `suppliers:read`.
+   *
    * @example
    * ```ts
    * const part = await client.catalog.parts.retrieve(
@@ -47,12 +49,44 @@ export class Parts extends APIResource {
   }
 
   /**
-   * Partially updates a part. Fields not provided retain their current values.
+   * Creates a part with the specified SKU and category.
+   *
+   * Inventory tracking for the new part starts at a zero on-hand quantity in the
+   * category's base unit.
+   *
+   * This endpoint requires the permissions: `parts:create`, `customers:update`,
+   * `suppliers:update`.
+   *
+   * @example
+   * ```ts
+   * const part = await client.catalog.parts.create({
+   *   category_id: 'ic_01ae7bd7bfd21ca0ab81e1357e',
+   *   sku: 'BRG-6204-2RS',
+   *   description: 'Deep groove ball bearing, 20x47x14mm',
+   * });
+   * ```
+   */
+  create(params: PartCreateParams, options?: RequestOptions): APIPromise<Part> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/parts', { query: { include }, body, ...options });
+  }
+
+  /**
+   * Partially updates a part.
+   *
+   * Fields not provided retain their current values.
+   *
+   * This endpoint requires the permissions: `parts:update`, `customers:update`,
+   * `suppliers:update`.
    *
    * @example
    * ```ts
    * const part = await client.catalog.parts.update(
    *   'pt_018d7bab53e864351f4c693a21',
+   *   {
+   *     description: 'Deep groove ball bearing, 20x47x14mm',
+   *     sku: 'BRG-6204-2RS',
+   *   },
    * );
    * ```
    */
@@ -66,19 +100,14 @@ export class Parts extends APIResource {
   }
 
   /**
-   * Returns a paginated list of parts for the current account.
+   * Deletes a part.
    *
-   * @example
-   * ```ts
-   * const listPart = await client.catalog.parts.list();
-   * ```
-   */
-  list(query: PartListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListPart> {
-    return this._client.get('/v1/catalog/parts', { query, ...options });
-  }
-
-  /**
-   * Deletes a part. Sets the deleted_at timestamp rather than removing the record.
+   * This is a soft delete: the part is marked deleted and no longer returned by
+   * other endpoints, but the record is retained. Deleting an already-deleted part
+   * returns an error.
+   *
+   * This endpoint requires the permissions: `parts:delete`, `customers:update`,
+   * `suppliers:update`.
    *
    * @example
    * ```ts
@@ -97,37 +126,45 @@ export class Parts extends APIResource {
  */
 export interface CreatePartRequest {
   /**
-   * Category ID.
+   * ID of the item category to place the part in.
+   *
+   * The category's unit group determines the base unit used for the part's rates
+   * (`unit_value`, `unit_cost`, `burn_rate`).
    */
   category_id: string;
 
   /**
-   * SKU.
+   * Stock keeping unit code for the part.
+   *
+   * Must be unique within the account; creating a part with a SKU already used by
+   * another item fails with a conflict error.
    */
   sku: string;
 
   /**
-   * Attribute IDs to connect to the part at creation time.
+   * IDs of existing attributes to link to the part at creation time.
    */
   attribute_ids?: Array<string>;
 
   /**
-   * Description.
+   * Free-form description of the part.
    */
   description?: string;
 
   /**
-   * Notes.
+   * Free-form notes about the part.
    */
   notes?: 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?: MaterialsAPI.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?: MaterialsAPI.RateInput;
 }
@@ -153,7 +190,10 @@ export interface ListPart {
 }
 
 /**
- * Part resource.
+ * A part in the account's catalog: a component used in production.
+ *
+ * Part-level data such as the SKU, description, category, pricing, and attributes
+ * lives on the underlying `item`.
  */
 export interface Part {
   /**
@@ -187,64 +227,84 @@ export interface Part {
  */
 export interface UpdatePartRequest {
   /**
-   * Description.
+   * New description for the part.
+   *
+   * Set to a string to replace the current description, or `null` to clear it.
    */
   description?: string | null;
 
   /**
-   * Notes.
+   * New notes for the part.
+   *
+   * Set to a string to replace the current notes, or `null` to clear them.
    */
   notes?: string | null;
 
   /**
-   * SKU.
+   * New stock keeping unit code for the part.
+   *
+   * Must remain unique within the account; a conflict error is returned if another
+   * item already uses it.
    */
   sku?: string;
 }
 
-export interface PartCreateParams {
+export interface PartListParams {
   /**
-   * Body param: Category ID.
+   * Filter by attribute IDs.
    */
-  category_id: string;
+  attribute_ids?: Array<string>;
 
   /**
-   * Body param: SKU.
+   * 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.
    */
-  include?: Array<
-    'item' | 'item.category' | 'item.unit_value' | 'item.unit_cost' | 'item.burn_rate' | 'item.attributes'
-  >;
+  cursor?: string;
 
   /**
-   * Body param: Attribute IDs to connect to the part at creation time.
+   * Filter parts created on or before this date.
    */
-  attribute_ids?: Array<string>;
+  end_date?: string;
 
   /**
-   * Body param: Description.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
-  description?: string;
+  include?: Array<
+    | 'item'
+    | 'item.category'
+    | 'item.category.properties'
+    | 'item.category.unit_group'
+    | 'item.unit_value'
+    | 'item.unit_cost'
+    | 'item.burn_rate'
+    | 'item.attributes'
+  >;
 
   /**
-   * Body param: Notes.
+   * Maximum number of results to return in a single page.
    */
-  notes?: string;
+  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?: MaterialsAPI.RateInput;
+  q?: string;
 
   /**
-   * Body param: RateInput represents the input for creating or updating a rate.
+   * Filter parts created on or after this date.
    */
-  unit_price?: MaterialsAPI.RateInput;
+  start_date?: string;
 }
 
 export interface PartRetrieveParams {
@@ -264,81 +324,89 @@ export interface PartRetrieveParams {
   >;
 }
 
-export interface PartUpdateParams {
+export interface PartCreateParams {
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Body param: ID of the item category to place the part in.
+   *
+   * The category's unit group determines the base unit used for the part's rates
+   * (`unit_value`, `unit_cost`, `burn_rate`).
    */
-  include?: Array<
-    'item' | 'item.category' | 'item.unit_value' | 'item.unit_cost' | 'item.burn_rate' | 'item.attributes'
-  >;
+  category_id: string;
 
   /**
-   * Body param: Description.
+   * Body param: Stock keeping unit code for the part.
+   *
+   * Must be unique within the account; creating a part with a SKU already used by
+   * another item fails with a conflict error.
    */
-  description?: string | null;
+  sku: string;
 
   /**
-   * Body param: Notes.
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
-  notes?: string | null;
+  include?: Array<
+    'item' | 'item.category' | 'item.unit_value' | 'item.unit_cost' | 'item.burn_rate' | 'item.attributes'
+  >;
 
   /**
-   * Body param: SKU.
+   * Body param: IDs of existing attributes to link to the part at creation time.
    */
-  sku?: string;
-}
+  attribute_ids?: Array<string>;
 
-export interface PartListParams {
   /**
-   * Filter by attribute IDs.
+   * Body param: Free-form description of the part.
    */
-  attribute_ids?: Array<string>;
+  description?: string;
 
   /**
-   * Filter by category IDs.
+   * Body param: Free-form notes about the part.
    */
-  category_ids?: Array<string>;
+  notes?: 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;
+  unit_cost?: MaterialsAPI.RateInput;
 
   /**
-   * Filter parts created on or before this date.
+   * Body param: A rate value with its numerator and denominator units, used in
+   * create and update requests.
    */
-  end_date?: string;
+  unit_price?: MaterialsAPI.RateInput;
+}
 
+export interface PartUpdateParams {
   /**
-   * 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'
-    | 'item.category'
-    | 'item.category.properties'
-    | 'item.category.unit_group'
-    | 'item.unit_value'
-    | 'item.unit_cost'
-    | 'item.burn_rate'
-    | 'item.attributes'
+    'item' | 'item.category' | 'item.unit_value' | 'item.unit_cost' | 'item.burn_rate' | 'item.attributes'
   >;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Body param: New description for the part.
+   *
+   * Set to a string to replace the current description, or `null` to clear it.
    */
-  limit?: number;
+  description?: string | null;
 
   /**
-   * Search query used to filter results.
+   * Body param: New notes for the part.
+   *
+   * Set to a string to replace the current notes, or `null` to clear them.
    */
-  q?: string;
+  notes?: string | null;
 
   /**
-   * Filter parts created on or after this date.
+   * Body param: New stock keeping unit code for the part.
+   *
+   * Must remain unique within the account; a conflict error is returned if another
+   * item already uses it.
    */
-  start_date?: string;
+  sku?: string;
 }
 
 export declare namespace Parts {
@@ -347,9 +415,9 @@ export declare namespace Parts {
     type ListPart as ListPart,
     type Part as Part,
     type UpdatePartRequest as UpdatePartRequest,
-    type PartCreateParams as PartCreateParams,
+    type PartListParams as PartListParams,
     type PartRetrieveParams as PartRetrieveParams,
+    type PartCreateParams as PartCreateParams,
     type PartUpdateParams as PartUpdateParams,
-    type PartListParams as PartListParams,
   };
 }