@augno/sdk 0.18.2 → 0.19.1

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

@@ -0,0 +1,296 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as APIKeysAPI from '../../auth/api-keys/api-keys';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+/**
+ * List and manage inventory items.
+ */
+export class Actions extends APIResource {
+  /**
+   * Reconciles inventory for multiple items by SKU in one call, the bulk equivalent
+   * of counting stock and correcting the books.
+   *
+   * `reconcile_type` controls whether each quantity is added to the item's current
+   * quantity (`addition`) or replaces it (`force`). The figure a `force` measures
+   * against is what is on hand net of demand nothing has covered, the same basis the
+   * single-item endpoint uses. The response reports each item as reconciled, skipped
+   * (e.g. unknown SKU), or errored (e.g. unknown unit), so a problem with one item
+   * does not fail the rest of the batch.
+   *
+   * Each correction is written to the item's inventory audit trail as a user
+   * correction, attributed to the caller.
+   *
+   * This endpoint requires the permission: `items:create`.
+   *
+   * @example
+   * ```ts
+   * const bulkReconcileItemsResponse =
+   *   await client.catalog.items.actions.bulkReconcile({
+   *     data: [
+   *       {
+   *         sku: 'ALM-2024-1001',
+   *         unit: 'kg',
+   *         quantity: '10.5',
+   *       },
+   *     ],
+   *     reconcile_type: 'addition',
+   *   });
+   * ```
+   */
+  bulkReconcile(
+    body: ActionBulkReconcileParams,
+    options?: RequestOptions,
+  ): APIPromise<BulkReconcileItemsResponse> {
+    return this._client.post('/v1/catalog/items/actions/bulk-reconcile', { body, ...options });
+  }
+}
+
+/**
+ * One item to reconcile in a bulk reconcile request.
+ */
+export interface BulkReconcileItemInput {
+  /**
+   * Quantity to apply, interpreted according to the request's `reconcile_type`.
+   *
+   * A decimal string rather than a number: a quantity that has been through a binary
+   * float is not the quantity you sent.
+   */
+  quantity: string;
+
+  /**
+   * SKU of the item to reconcile.
+   *
+   * Items whose SKU does not match an existing item are reported in the response's
+   * `skipped_items` rather than failing the request.
+   */
+  sku: string;
+
+  /**
+   * Abbreviation of a unit available to your account (e.g. `kg`).
+   *
+   * The unit is checked for existence only: the quantity is always recorded in the
+   * item's own base unit, so send figures already expressed in that unit. Rows
+   * naming an abbreviation that matches no built-in or account-defined unit are
+   * reported in the response's `errors`.
+   */
+  unit: string;
+}
+
+/**
+ * Request to reconcile inventory for many items at once.
+ */
+export interface BulkReconcileItemsRequest {
+  /**
+   * Items to reconcile.
+   */
+  data: Array<BulkReconcileItemInput>;
+
+  /**
+   * How each item's quantity is applied to its current quantity.
+   *
+   * - `addition`: adds the quantity to the item's current quantity.
+   * - `force`: sets the item's current quantity to exactly the given quantity.
+   */
+  reconcile_type: string;
+}
+
+/**
+ * The outcome of a bulk inventory reconciliation, reported as three separate
+ * lists.
+ */
+export interface BulkReconcileItemsResponse {
+  /**
+   * A single page of resources, together with the metadata needed to page through
+   * the rest of the result set.
+   */
+  errors: ListReconcileErrorResult | null;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'bulk_reconcile_items_response';
+
+  /**
+   * A single page of resources, together with the metadata needed to page through
+   * the rest of the result set.
+   */
+  reconciled_items: ListReconciledItemResult | null;
+
+  /**
+   * A single page of resources, together with the metadata needed to page through
+   * the rest of the result set.
+   */
+  skipped_items: ListSkippedItemResult | null;
+}
+
+/**
+ * A single page of resources, together with the metadata needed to page through
+ * the rest of the result set.
+ */
+export interface ListReconcileErrorResult {
+  /**
+   * Resources in this page.
+   */
+  data: Array<ReconcileErrorResult>;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'list';
+
+  /**
+   * PageInfo describes where the current page sits within a paginated result set and
+   * how to move to the adjacent pages.
+   *
+   * Page a list by following the URLs below rather than assembling cursors yourself.
+   * For a top-level list endpoint the URL repeats the original request's query
+   * string with only the cursor swapped, so following it preserves the same filters,
+   * search term, and page size.
+   */
+  page_info: APIKeysAPI.PageInfo;
+}
+
+/**
+ * A single page of resources, together with the metadata needed to page through
+ * the rest of the result set.
+ */
+export interface ListReconciledItemResult {
+  /**
+   * Resources in this page.
+   */
+  data: Array<ReconciledItemResult>;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'list';
+
+  /**
+   * PageInfo describes where the current page sits within a paginated result set and
+   * how to move to the adjacent pages.
+   *
+   * Page a list by following the URLs below rather than assembling cursors yourself.
+   * For a top-level list endpoint the URL repeats the original request's query
+   * string with only the cursor swapped, so following it preserves the same filters,
+   * search term, and page size.
+   */
+  page_info: APIKeysAPI.PageInfo;
+}
+
+/**
+ * A single page of resources, together with the metadata needed to page through
+ * the rest of the result set.
+ */
+export interface ListSkippedItemResult {
+  /**
+   * Resources in this page.
+   */
+  data: Array<SkippedItemResult>;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'list';
+
+  /**
+   * PageInfo describes where the current page sits within a paginated result set and
+   * how to move to the adjacent pages.
+   *
+   * Page a list by following the URLs below rather than assembling cursors yourself.
+   * For a top-level list endpoint the URL repeats the original request's query
+   * string with only the cursor swapped, so following it preserves the same filters,
+   * search term, and page size.
+   */
+  page_info: APIKeysAPI.PageInfo;
+}
+
+/**
+ * A submitted row that could not be reconciled.
+ */
+export interface ReconcileErrorResult {
+  /**
+   * Error message.
+   */
+  error: string;
+
+  /**
+   * Item SKU.
+   */
+  sku: string;
+}
+
+/**
+ * An item whose on-hand quantity was successfully reconciled.
+ *
+ * Both quantities are expressed in the item's own base unit, not in the unit
+ * submitted with the request.
+ */
+export interface ReconciledItemResult {
+  /**
+   * Item ID.
+   */
+  item_id: string;
+
+  /**
+   * Quantity after the reconciliation, as a decimal string.
+   */
+  new_quantity: string;
+
+  /**
+   * Quantity before the reconciliation, as a decimal string.
+   */
+  previous_quantity: string;
+
+  /**
+   * Item SKU.
+   */
+  sku: string;
+}
+
+/**
+ * A submitted row that was skipped rather than reconciled.
+ */
+export interface SkippedItemResult {
+  /**
+   * Human-readable reason the item was skipped.
+   */
+  reason: string;
+
+  /**
+   * Item SKU.
+   */
+  sku: string;
+}
+
+export interface ActionBulkReconcileParams {
+  /**
+   * Items to reconcile.
+   */
+  data: Array<BulkReconcileItemInput>;
+
+  /**
+   * How each item's quantity is applied to its current quantity.
+   *
+   * - `addition`: adds the quantity to the item's current quantity.
+   * - `force`: sets the item's current quantity to exactly the given quantity.
+   */
+  reconcile_type: string;
+}
+
+export declare namespace Actions {
+  export {
+    type BulkReconcileItemInput as BulkReconcileItemInput,
+    type BulkReconcileItemsRequest as BulkReconcileItemsRequest,
+    type BulkReconcileItemsResponse as BulkReconcileItemsResponse,
+    type ListReconcileErrorResult as ListReconcileErrorResult,
+    type ListReconciledItemResult as ListReconciledItemResult,
+    type ListSkippedItemResult as ListSkippedItemResult,
+    type ReconcileErrorResult as ReconcileErrorResult,
+    type ReconciledItemResult as ReconciledItemResult,
+    type SkippedItemResult as SkippedItemResult,
+    type ActionBulkReconcileParams as ActionBulkReconcileParams,
+  };
+}

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

@@ -1,18 +1,38 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Actions,
+  type BulkReconcileItemInput,
+  type BulkReconcileItemsRequest,
+  type BulkReconcileItemsResponse,
+  type ListReconcileErrorResult,
+  type ListReconciledItemResult,
+  type ListSkippedItemResult,
+  type ReconcileErrorResult,
+  type ReconciledItemResult,
+  type SkippedItemResult,
+  type ActionBulkReconcileParams,
+} from './actions';
 export { Attributes, type AttributeUpdateParams, type AttributeDeleteParams } from './attributes';
+export {
+  Inventory,
+  type ComputedQuantity,
+  type ItemInventory,
+  type QuantityInput,
+  type UpdateItemInventoryRequest,
+  type InventoryUpdateResponse,
+  type InventoryListParams,
+  type InventoryUpdateParams,
+} from './inventory';
 export {
   Items,
   type Item,
   type ItemCategory,
-  type ItemInventory,
   type ItemLotDefault,
   type ListItem,
-  type Quantity,
   type Rate,
   type ItemListParams,
   type ItemRetrieveParams,
-  type ItemRetrieveInventoryParams,
   type ItemRetrieveLotDefaultParams,
   type ItemChangeCategoryParams,
 } from './items';

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

@@ -0,0 +1,294 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as UnitsAPI from '../units/units';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * List and manage inventory items.
+ */
+export class Inventory extends APIResource {
+  /**
+   * Returns the stock position for an item: what is on hand, what is reserved
+   * against existing orders, what is free to promise, and what is short.
+   *
+   * Stock your account either owns or holds counts toward the on-hand figure, so
+   * customer-supplied material sitting in your facility is included. All four
+   * quantities are reported in the base unit of the item's category.
+   *
+   * This endpoint requires the permission: `items:read`.
+   *
+   * @example
+   * ```ts
+   * const itemInventory =
+   *   await client.catalog.items.inventory.list(
+   *     'it_pej07ckhvu62',
+   *   );
+   * ```
+   */
+  list(
+    id: string,
+    query: InventoryListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ItemInventory> {
+    return this._client.get(path`/v1/catalog/items/${id}/inventory`, { query, ...options });
+  }
+
+  /**
+   * Adjusts or reconciles the quantity of an item you hold.
+   *
+   * With `operation` set to `adjust` (the behavior when it is omitted), `quantity`
+   * is added to the current quantity; with `reconcile`, the current quantity is set
+   * to exactly `quantity`. Either way it is the resulting difference that gets
+   * written, so a difference of zero moves no stock.
+   *
+   * The figure a `reconcile` measures against is what is on hand net of demand
+   * nothing has covered — the same figure `available_to_promise` is derived from,
+   * not the raw on-hand total. Reconciling to the quantity already reported
+   * therefore writes nothing.
+   *
+   * Stock that arrives is allocated against unfilled demand for the item, so an
+   * adjustment can settle a shortfall instead of raising the quantity free to
+   * promise. That allocation happens just after the request rather than inside it,
+   * because it walks every open issue for the item. The change is recorded in the
+   * item's inventory audit trail as a user correction attributed to the caller.
+   *
+   * This endpoint requires the permission: `items:update`.
+   *
+   * @example
+   * ```ts
+   * const inventory =
+   *   await client.catalog.items.inventory.update(
+   *     'it_pej07ckhvu62',
+   *     {
+   *       quantity: {
+   *         value: '10.5',
+   *         unit_id: 'un_82bd37dae5po',
+   *       },
+   *       customer_id: 'ac_opnlh43ymyee',
+   *       location_id: 'lc_yonnys0hx3ju',
+   *       operation: 'adjust',
+   *     },
+   *   );
+   * ```
+   */
+  update(
+    id: string,
+    body: InventoryUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<InventoryUpdateResponse> {
+    return this._client.patch(path`/v1/catalog/items/${id}/inventory`, { body, ...options });
+  }
+}
+
+/**
+ * An amount calculated on demand rather than stored.
+ *
+ * The same shape as a quantity minus the ID, because nothing was written: it is
+ * derived per request, such as a total rolled up across invoiced lines for one
+ * analysis.
+ */
+export interface ComputedQuantity {
+  /**
+   * Formatted value with unit abbreviation (e.g. "1,200 pr").
+   */
+  display_value: string;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'computed_quantity';
+
+  /**
+   * Unit of measurement used for conversions and product quantities.
+   */
+  unit: UnitsAPI.Unit | null;
+
+  /**
+   * Raw decimal value, as a string to preserve precision.
+   *
+   * This is the unformatted machine value; see `display_value` for the
+   * human-readable rendering.
+   */
+  value: string;
+}
+
+/**
+ * The stock position for an item: what is in stock, what is already committed, and
+ * what is still free to sell.
+ *
+ * All four quantities are reported in the same unit — the base unit of the item's
+ * category. Derived figures, not stored rows: each is netted out of the ledger at
+ * read time, so none of them carries a quantity id.
+ */
+export interface ItemInventory {
+  /**
+   * An amount calculated on demand rather than stored.
+   *
+   * The same shape as a quantity minus the ID, because nothing was written: it is
+   * derived per request, such as a total rolled up across invoiced lines for one
+   * analysis.
+   */
+  available_to_promise: ComputedQuantity | null;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'item_inventory';
+
+  /**
+   * An amount calculated on demand rather than stored.
+   *
+   * The same shape as a quantity minus the ID, because nothing was written: it is
+   * derived per request, such as a total rolled up across invoiced lines for one
+   * analysis.
+   */
+  on_hand: ComputedQuantity | null;
+
+  /**
+   * An amount calculated on demand rather than stored.
+   *
+   * The same shape as a quantity minus the ID, because nothing was written: it is
+   * derived per request, such as a total rolled up across invoiced lines for one
+   * analysis.
+   */
+  reserved: ComputedQuantity | null;
+
+  /**
+   * An amount calculated on demand rather than stored.
+   *
+   * The same shape as a quantity minus the ID, because nothing was written: it is
+   * derived per request, such as a total rolled up across invoiced lines for one
+   * analysis.
+   */
+  short: ComputedQuantity | null;
+}
+
+/**
+ * An amount together with the unit it is expressed in.
+ *
+ * The unit may be a currency, so money amounts such as a credit limit are written
+ * the same way as physical amounts like weights or counts.
+ */
+export interface QuantityInput {
+  /**
+   * ID of the unit of measure for the value.
+   */
+  unit_id: string;
+
+  /**
+   * Decimal value, as a string to preserve precision.
+   */
+  value: string;
+}
+
+/**
+ * Request to adjust or reconcile inventory for an item.
+ */
+export interface UpdateItemInventoryRequest {
+  /**
+   * An amount together with the unit it is expressed in.
+   *
+   * The unit may be a currency, so money amounts such as a credit limit are written
+   * the same way as physical amounts like weights or counts.
+   */
+  quantity: QuantityInput;
+
+  /**
+   * ID of the customer account that owns the resulting inventory.
+   *
+   * Use this for stock you hold but do not own, such as customer-supplied material.
+   * It only affects quantity being added: your account stays the holder, the
+   * customer becomes the owner, and the current quantity a `reconcile` measures
+   * against is still your account's. Requires edit access to that customer.
+   */
+  customer_id?: string;
+
+  /**
+   * ID of the location to record the inventory change against.
+   *
+   * Must be a location in your account.
+   */
+  location_id?: string;
+
+  /**
+   * Lot number to record the inventory change against.
+   *
+   * The lot is created for the item if it does not already exist.
+   */
+  lot_number?: string;
+
+  /**
+   * How `quantity` is applied.
+   *
+   * - `adjust`: adds `quantity` to the current quantity.
+   * - `reconcile`: sets the current quantity to exactly `quantity`.
+   */
+  operation?: 'adjust' | 'reconcile';
+}
+
+export interface InventoryUpdateResponse {}
+
+export interface InventoryListParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'on_hand' | 'reserved' | 'available_to_promise' | 'short'>;
+}
+
+export interface InventoryUpdateParams {
+  /**
+   * An amount together with the unit it is expressed in.
+   *
+   * The unit may be a currency, so money amounts such as a credit limit are written
+   * the same way as physical amounts like weights or counts.
+   */
+  quantity: QuantityInput;
+
+  /**
+   * ID of the customer account that owns the resulting inventory.
+   *
+   * Use this for stock you hold but do not own, such as customer-supplied material.
+   * It only affects quantity being added: your account stays the holder, the
+   * customer becomes the owner, and the current quantity a `reconcile` measures
+   * against is still your account's. Requires edit access to that customer.
+   */
+  customer_id?: string;
+
+  /**
+   * ID of the location to record the inventory change against.
+   *
+   * Must be a location in your account.
+   */
+  location_id?: string;
+
+  /**
+   * Lot number to record the inventory change against.
+   *
+   * The lot is created for the item if it does not already exist.
+   */
+  lot_number?: string;
+
+  /**
+   * How `quantity` is applied.
+   *
+   * - `adjust`: adds `quantity` to the current quantity.
+   * - `reconcile`: sets the current quantity to exactly `quantity`.
+   */
+  operation?: 'adjust' | 'reconcile';
+}
+
+export declare namespace Inventory {
+  export {
+    type ComputedQuantity as ComputedQuantity,
+    type ItemInventory as ItemInventory,
+    type QuantityInput as QuantityInput,
+    type UpdateItemInventoryRequest as UpdateItemInventoryRequest,
+    type InventoryUpdateResponse as InventoryUpdateResponse,
+    type InventoryListParams as InventoryListParams,
+    type InventoryUpdateParams as InventoryUpdateParams,
+  };
+}