@augno/sdk 0.1.9 → 0.7.1

package/src/resources/catalog/products.ts

@@ -14,25 +14,26 @@ import { path } from '../../internal/utils/path';
  */
 export class Products extends APIResource {
   /**
-   * Creates a product.
+   * Returns a paginated list of products for the target account.
+   *
+   * This endpoint requires the permissions: `items:read`, `customers:read`,
+   * `suppliers:read`.
    *
    * @example
    * ```ts
-   * const product = await client.catalog.products.create({
-   *   category_id: 'ic_01ae7bd7bfd21ca0ab81e1357e',
-   *   sku: 'ALM-2024-1001',
-   *   type: 'sale',
-   * });
+   * const listProduct = await client.catalog.products.list();
    * ```
    */
-  create(params: ProductCreateParams, options?: RequestOptions): APIPromise<Product> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/products', { query: { include }, body, ...options });
+  list(query: ProductListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListProduct> {
+    return this._client.get('/v1/catalog/products', { query, ...options });
   }
 
   /**
    * Returns a product by ID.
    *
+   * This endpoint requires the permissions: `items:read`, `customers:read`,
+   * `suppliers:read`.
+   *
    * @example
    * ```ts
    * const product = await client.catalog.products.retrieve(
@@ -48,13 +49,39 @@ export class Products extends APIResource {
     return this._client.get(path`/v1/catalog/products/${id}`, { query, ...options });
   }
 
+  /**
+   * Creates a product and its backing inventory item.
+   *
+   * The new item starts with zero on-hand inventory, and its pricing defaults to
+   * zero rates in the category's base unit unless `unit_price` or `unit_cost` is
+   * provided.
+   *
+   * This endpoint requires the permission: `items:create`.
+   *
+   * @example
+   * ```ts
+   * const product = await client.catalog.products.create({
+   *   category_id: 'ic_01ae7bd7bfd21ca0ab81e1357e',
+   *   sku: 'ALM-2024-1001',
+   *   type: 'sale',
+   * });
+   * ```
+   */
+  create(params: ProductCreateParams, options?: RequestOptions): APIPromise<Product> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/products', { query: { include }, body, ...options });
+  }
+
   /**
    * Partially updates a product.
    *
+   * This endpoint requires the permission: `items:update`.
+   *
    * @example
    * ```ts
    * const product = await client.catalog.products.update(
    *   'pd_013c29ab3f1518d0004094c316',
+   *   { sku: 'SKU-002' },
    * );
    * ```
    */
@@ -67,21 +94,11 @@ export class Products extends APIResource {
     return this._client.patch(path`/v1/catalog/products/${id}`, { query: { include }, body, ...options });
   }
 
-  /**
-   * Returns a paginated list of products for the target account.
-   *
-   * @example
-   * ```ts
-   * const listProduct = await client.catalog.products.list();
-   * ```
-   */
-  list(query: ProductListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListProduct> {
-    return this._client.get('/v1/catalog/products', { query, ...options });
-  }
-
   /**
    * Soft-deletes a product and returns the deleted product.
    *
+   * This endpoint requires the permission: `items:delete`.
+   *
    * @example
    * ```ts
    * const product = await client.catalog.products.delete(
@@ -101,6 +118,8 @@ export class Products extends APIResource {
   /**
    * Changes the product line assignment for a product.
    *
+   * This endpoint requires the permission: `items:update`.
+   *
    * @example
    * ```ts
    * const product =
@@ -128,17 +147,31 @@ export class Products extends APIResource {
  */
 export interface CreateProductRequest {
   /**
-   * Category ID.
+   * ID of the item category for the product's item.
+   *
+   * The category's unit group determines the default units used for the product's
+   * pricing rates and inventory tracking.
    */
   category_id: string;
 
   /**
-   * SKU.
+   * Stock keeping unit code for the product's item.
+   *
+   * Must be unique within the account; creation fails with a conflict error if
+   * another item already uses it.
    */
   sku: string;
 
   /**
-   * Product type code (e.g. sale, sample).
+   * Product type code, which determines how the product behaves on orders and
+   * invoices.
+   *
+   * - `sale`: a standard sellable product.
+   * - `service`: a non-physical service line, such as labor or installation.
+   * - `shipping`: a shipping charge applied to an order.
+   * - `credit`: a credit applied against an order or invoice.
+   * - `return`: a returned product (RMA).
+   * - `tax`: a tax line.
    */
   type: 'sale' | 'service' | 'shipping' | 'credit' | 'return' | 'tax';
 
@@ -148,32 +181,41 @@ export interface CreateProductRequest {
   attribute_ids?: Array<string>;
 
   /**
-   * Description.
+   * Free-form description of the product.
    */
   description?: string;
 
   /**
-   * Notes.
+   * Free-form notes about the product.
    */
   notes?: string;
 
   /**
-   * Whether visible in the customer portal.
+   * Whether the product is shown to buyers in the customer portal.
+   *
+   * - `visible`: buyers can see and order the product in the portal.
+   * - `hidden`: the product is concealed from the portal but remains usable
+   *   internally.
+   *
+   * When omitted, the product is created hidden, so it must be set to `visible`
+   * before buyers can see it.
    */
   portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Product line ID.
+   * ID of the product line to assign the product to.
    */
   product_line_id?: 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;
 }
@@ -199,7 +241,8 @@ export interface ListProduct {
 }
 
 /**
- * Product with expandable item, product line, and product type.
+ * Product pairs an inventory item with how it is sold: its product type, optional
+ * product line, and customer portal visibility.
  */
 export interface Product {
   /**
@@ -223,17 +266,32 @@ export interface Product {
   object: 'product';
 
   /**
-   * Product portal visibility.
+   * Whether the product is shown to buyers in the customer portal.
+   *
+   * - `visible`: buyers can see and order the product in the portal.
+   * - `hidden`: the product is concealed from the portal but remains usable
+   *   internally.
    */
   portal_visibility: 'visible' | 'hidden';
 
   /**
    * Product line resource.
+   *
+   * A product line groups related products in your catalog and carries the default
+   * commission policy, freight policy, and unit group for those products.
    */
   product_line: ProductLinesAPI.ProductLine | null;
 
   /**
-   * Product type code.
+   * Product type code, which determines how the product behaves on orders and
+   * invoices.
+   *
+   * - `sale`: a standard sellable product.
+   * - `service`: a non-physical service line, such as labor or installation.
+   * - `shipping`: a shipping charge applied to an order.
+   * - `credit`: a credit applied against an order or invoice.
+   * - `return`: a returned product (RMA).
+   * - `tax`: a tax line.
    */
   type: 'sale' | 'service' | 'shipping' | 'credit' | 'return' | 'tax';
 
@@ -248,50 +306,76 @@ export interface Product {
  */
 export interface UpdateProductRequest {
   /**
-   * Description.
+   * Free-form description of the product.
+   *
+   * Send `null` to clear.
    */
   description?: string | null;
 
   /**
-   * Notes.
+   * Free-form notes about the product.
+   *
+   * Send `null` to clear.
    */
   notes?: string | null;
 
   /**
-   * Whether visible in the customer portal.
+   * Whether the product is shown to buyers in the customer portal.
+   *
+   * - `visible`: buyers can see and order the product in the portal.
+   * - `hidden`: the product is concealed from the portal but remains usable
+   *   internally.
    */
   portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * SKU.
+   * New stock keeping unit code for the product's item.
+   *
+   * Must be unique within the account; the update fails with a conflict error 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_price?: MaterialsAPI.RateInput;
 }
 
-export interface ProductCreateParams {
+export interface ProductListParams {
   /**
-   * 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>;
 
   /**
-   * Body param: Product type code (e.g. sale, sample).
+   * 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.
    */
-  type: 'sale' | 'service' | 'shipping' | 'credit' | 'return' | 'tax';
+  cursor?: string;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Filter by customer IDs.
+   */
+  customer_ids?: Array<string>;
+
+  /**
+   * End of creation date range.
+   */
+  end_date?: string;
+
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
   include?: Array<
     | 'product_line'
@@ -313,39 +397,31 @@ export interface ProductCreateParams {
   >;
 
   /**
-   * Body param: Attribute IDs to connect to the product at creation time.
-   */
-  attribute_ids?: Array<string>;
-
-  /**
-   * Body param: Description.
-   */
-  description?: string;
-
-  /**
-   * Body param: Notes.
+   * Maximum number of results to return in a single page.
    */
-  notes?: string;
+  limit?: number;
 
   /**
-   * Body param: Whether visible in the customer portal.
+   * Filter by customer portal visibility.
    */
   portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Body param: Product line ID.
+   * Filter by product line IDs.
    */
-  product_line_id?: string;
+  product_line_ids?: Array<string>;
 
   /**
-   * 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.
+   * Start of creation date range.
    */
-  unit_price?: MaterialsAPI.RateInput;
+  start_date?: string;
 }
 
 export interface ProductRetrieveParams {
@@ -373,7 +449,36 @@ export interface ProductRetrieveParams {
   >;
 }
 
-export interface ProductUpdateParams {
+export interface ProductCreateParams {
+  /**
+   * Body param: ID of the item category for the product's item.
+   *
+   * The category's unit group determines the default units used for the product's
+   * pricing rates and inventory tracking.
+   */
+  category_id: string;
+
+  /**
+   * Body param: Stock keeping unit code for the product's item.
+   *
+   * Must be unique within the account; creation fails with a conflict error if
+   * another item already uses it.
+   */
+  sku: string;
+
+  /**
+   * Body param: Product type code, which determines how the product behaves on
+   * orders and invoices.
+   *
+   * - `sale`: a standard sellable product.
+   * - `service`: a non-physical service line, such as labor or installation.
+   * - `shipping`: a shipping charge applied to an order.
+   * - `credit`: a credit applied against an order or invoice.
+   * - `return`: a returned product (RMA).
+   * - `tax`: a tax line.
+   */
+  type: 'sale' | 'service' | 'shipping' | 'credit' | 'return' | 'tax';
+
   /**
    * Query param: Sub-objects to expand in the response. When omitted, sub-objects
    * are returned as `null`.
@@ -398,60 +503,54 @@ export interface ProductUpdateParams {
   >;
 
   /**
-   * Body param: Description.
-   */
-  description?: string | null;
-
-  /**
-   * Body param: Notes.
-   */
-  notes?: string | null;
-
-  /**
-   * Body param: Whether visible in the customer portal.
-   */
-  portal_visibility?: 'visible' | 'hidden';
-
-  /**
-   * Body param: SKU.
+   * Body param: Attribute IDs to connect to the product at creation time.
    */
-  sku?: string;
+  attribute_ids?: Array<string>;
 
   /**
-   * Body param: RateInput represents the input for creating or updating a rate.
+   * Body param: Free-form description of the product.
    */
-  unit_price?: MaterialsAPI.RateInput;
-}
+  description?: string;
 
-export interface ProductListParams {
   /**
-   * Filter by attribute IDs.
+   * Body param: Free-form notes about the product.
    */
-  attribute_ids?: Array<string>;
+  notes?: string;
 
   /**
-   * Filter by category IDs.
+   * Body param: Whether the product is shown to buyers in the customer portal.
+   *
+   * - `visible`: buyers can see and order the product in the portal.
+   * - `hidden`: the product is concealed from the portal but remains usable
+   *   internally.
+   *
+   * When omitted, the product is created hidden, so it must be set to `visible`
+   * before buyers can see it.
    */
-  category_ids?: Array<string>;
+  portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: ID of the product line to assign the product to.
    */
-  cursor?: string;
+  product_line_id?: string;
 
   /**
-   * Filter by customer IDs.
+   * Body param: A rate value with its numerator and denominator units, used in
+   * create and update requests.
    */
-  customer_ids?: Array<string>;
+  unit_cost?: MaterialsAPI.RateInput;
 
   /**
-   * End of creation date range.
+   * 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 ProductUpdateParams {
   /**
-   * 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<
     | 'product_line'
@@ -473,29 +572,41 @@ export interface ProductListParams {
   >;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Body param: Free-form description of the product.
+   *
+   * Send `null` to clear.
    */
-  limit?: number;
+  description?: string | null;
 
   /**
-   * Filter by customer portal visibility.
+   * Body param: Free-form notes about the product.
+   *
+   * Send `null` to clear.
    */
-  portal_visibility?: 'visible' | 'hidden';
+  notes?: string | null;
 
   /**
-   * Filter by product line IDs.
+   * Body param: Whether the product is shown to buyers in the customer portal.
+   *
+   * - `visible`: buyers can see and order the product in the portal.
+   * - `hidden`: the product is concealed from the portal but remains usable
+   *   internally.
    */
-  product_line_ids?: Array<string>;
+  portal_visibility?: 'visible' | 'hidden';
 
   /**
-   * Search query used to filter results.
+   * Body param: New stock keeping unit code for the product's item.
+   *
+   * Must be unique within the account; the update fails with a conflict error if
+   * another item already uses it.
    */
-  q?: string;
+  sku?: string;
 
   /**
-   * Start of creation date range.
+   * Body param: A rate value with its numerator and denominator units, used in
+   * create and update requests.
    */
-  start_date?: string;
+  unit_price?: MaterialsAPI.RateInput;
 }
 
 export interface ProductDeleteParams {
@@ -559,10 +670,10 @@ export declare namespace Products {
     type ListProduct as ListProduct,
     type Product as Product,
     type UpdateProductRequest as UpdateProductRequest,
-    type ProductCreateParams as ProductCreateParams,
+    type ProductListParams as ProductListParams,
     type ProductRetrieveParams as ProductRetrieveParams,
+    type ProductCreateParams as ProductCreateParams,
     type ProductUpdateParams as ProductUpdateParams,
-    type ProductListParams as ProductListParams,
     type ProductDeleteParams as ProductDeleteParams,
     type ProductChangeProductLineParams as ProductChangeProductLineParams,
   };