@augno/sdk 0.13.4 → 0.14.0

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

@@ -0,0 +1,129 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as JobsAPI from '../../core/jobs';
+import * as ActionsAPI from '../item-categories/actions';
+import * as MaterialsAPI from '../materials/materials';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+/**
+ * List and manage parts.
+ */
+export class Actions extends APIResource {
+  /**
+   * Creates or updates multiple parts for the account, matched by SKU, then writes
+   * asynchronously — 202 with a job to poll.
+   *
+   * @example
+   * ```ts
+   * const job = await client.catalog.parts.actions.bulkUpsert({
+   *   parts: [
+   *     {
+   *       sku: 'BRG-6204-2RS',
+   *       category: { id: 'ic_d06g9c6yc9ck' },
+   *       properties: [],
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  bulkUpsert(body: ActionBulkUpsertParams, options?: RequestOptions): APIPromise<JobsAPI.Job> {
+    return this._client.post('/v1/catalog/parts/actions/bulk-upsert', { body, ...options });
+  }
+}
+
+/**
+ * BulkUpsertPartsRequest is the request to bulk upsert parts.
+ */
+export interface BulkUpsertPartsRequest {
+  /**
+   * Parts to create or update, matched by SKU within the account.
+   */
+  parts: Array<UpsertPartInput>;
+}
+
+/**
+ * UpsertPartInput is the input for a single part in a bulk upsert operation.
+ */
+export interface UpsertPartInput {
+  /**
+   * -------------------------- Named Object -------------------------- Identifies an
+   * object by its id or its name. An id wins when both are given.
+   */
+  category: ActionsAPI.ObjectIdentifier;
+
+  /**
+   * Properties to attach to the part, matched/created by name + value. Additive —
+   * existing attributes are not removed.
+   */
+  properties: Array<UpsertPartProperty>;
+
+  /**
+   * SKU for the part, matched against existing parts in the account: a match updates
+   * in place, otherwise a part is created. A SKU held by a non-part item fails that
+   * row.
+   */
+  sku: string;
+
+  /**
+   * Free-form description of the part.
+   */
+  description?: string;
+
+  /**
+   * Free-form notes about the part.
+   */
+  notes?: string;
+
+  /**
+   * A value expressed as a ratio of two units, supplied on create and update
+   * requests.
+   *
+   * A unit price, for example, has a currency as its numerator unit and the unit the
+   * product is bought or sold by as its denominator.
+   */
+  unit_cost?: MaterialsAPI.RateInput;
+
+  /**
+   * A value expressed as a ratio of two units, supplied on create and update
+   * requests.
+   *
+   * A unit price, for example, has a currency as its numerator unit and the unit the
+   * product is bought or sold by as its denominator.
+   */
+  unit_price?: MaterialsAPI.RateInput;
+}
+
+/**
+ * UpsertPartProperty is a property name + value pair attached to a part. The
+ * property and its value (an attribute) are created if they do not yet exist.
+ */
+export interface UpsertPartProperty {
+  /**
+   * Property name (e.g. "Material"). Matched case-insensitively; created if missing.
+   */
+  name: string;
+
+  /**
+   * Property value (e.g. "Steel"). Matched exactly; created under the property if
+   * missing.
+   */
+  value: string;
+}
+
+export interface ActionBulkUpsertParams {
+  /**
+   * Parts to create or update, matched by SKU within the account.
+   */
+  parts: Array<UpsertPartInput>;
+}
+
+export declare namespace Actions {
+  export {
+    type BulkUpsertPartsRequest as BulkUpsertPartsRequest,
+    type UpsertPartInput as UpsertPartInput,
+    type UpsertPartProperty as UpsertPartProperty,
+    type ActionBulkUpsertParams as ActionBulkUpsertParams,
+  };
+}

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

@@ -0,0 +1,20 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Actions,
+  type BulkUpsertPartsRequest,
+  type UpsertPartInput,
+  type UpsertPartProperty,
+  type ActionBulkUpsertParams,
+} from './actions';
+export {
+  Parts,
+  type CreatePartRequest,
+  type ListPart,
+  type Part,
+  type UpdatePartRequest,
+  type PartListParams,
+  type PartRetrieveParams,
+  type PartCreateParams,
+  type PartUpdateParams,
+} from './parts';

package/src/resources/catalog/parts/parts.ts

@@ -0,0 +1,476 @@
+// 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 * as ItemsAPI from '../items/items';
+import * as MaterialsAPI from '../materials/materials';
+import * as ActionsAPI from './actions';
+import {
+  ActionBulkUpsertParams,
+  Actions,
+  BulkUpsertPartsRequest,
+  UpsertPartInput,
+  UpsertPartProperty,
+} from './actions';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * List and manage parts.
+ */
+export class Parts extends APIResource {
+  actions: ActionsAPI.Actions = new ActionsAPI.Actions(this._client);
+
+  /**
+   * Returns a paginated list of parts for the current account, most recently created
+   * first.
+   *
+   * The `q` search term matches the part's SKU or description. When it is supplied,
+   * the parts whose SKU matches it most closely are returned first, ordered by
+   * creation time within each level of match.
+   *
+   * This endpoint requires the permissions: `parts:read`, `customers:read`,
+   * `suppliers:read`.
+   *
+   * @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 });
+  }
+
+  /**
+   * 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(
+   *   'pt_coba9fgvd84c',
+   * );
+   * ```
+   */
+  retrieve(
+    id: string,
+    query: PartRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Part> {
+    return this._client.get(path`/v1/catalog/parts/${id}`, { query, ...options });
+  }
+
+  /**
+   * 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_d06g9c6yc9ck',
+   *   sku: 'BRG-6204-2RS',
+   *   attribute_ids: ['at_rf1w295jt5ia'],
+   *   description: 'Deep groove ball bearing, 20x47x14mm',
+   *   notes:
+   *     'OEM-equivalent; verify shielding type before substitution.',
+   *   unit_cost: {
+   *     value: '9.40',
+   *     numerator_unit_id: 'un_82bd37dae5po',
+   *     denominator_unit_id: 'un_82bd37dae5po',
+   *   },
+   *   unit_price: {
+   *     value: '14.99',
+   *     numerator_unit_id: 'un_82bd37dae5po',
+   *     denominator_unit_id: 'un_82bd37dae5po',
+   *   },
+   * });
+   * ```
+   */
+  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. Only the SKU, description, and
+   * notes are editable here; the part's category and attributes are changed through
+   * the item endpoints.
+   *
+   * This endpoint requires the permissions: `parts:update`, `customers:update`,
+   * `suppliers:update`.
+   *
+   * @example
+   * ```ts
+   * const part = await client.catalog.parts.update(
+   *   'pt_coba9fgvd84c',
+   *   {
+   *     description: 'Deep groove ball bearing, 20x47x14mm',
+   *     notes:
+   *       'Superseded by low-friction variant; keep for legacy assemblies.',
+   *     sku: 'BRG-6204-2RS',
+   *   },
+   * );
+   * ```
+   */
+  update(
+    id: string,
+    params: PartUpdateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Part> {
+    const { include, ...body } = params ?? {};
+    return this._client.patch(path`/v1/catalog/parts/${id}`, { query: { include }, body, ...options });
+  }
+
+  /**
+   * Deletes a part.
+   *
+   * 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
+   * const part = await client.catalog.parts.delete(
+   *   'pt_coba9fgvd84c',
+   * );
+   * ```
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<Part> {
+    return this._client.delete(path`/v1/catalog/parts/${id}`, options);
+  }
+}
+
+/**
+ * Request to create a part.
+ */
+export interface CreatePartRequest {
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * IDs of existing attributes to link to the part at creation time.
+   */
+  attribute_ids?: Array<string>;
+
+  /**
+   * Free-form description of the part.
+   */
+  description?: string;
+
+  /**
+   * Free-form notes about the part.
+   */
+  notes?: string;
+
+  /**
+   * A value expressed as a ratio of two units, supplied on create and update
+   * requests.
+   *
+   * A unit price, for example, has a currency as its numerator unit and the unit the
+   * product is bought or sold by as its denominator.
+   */
+  unit_cost?: MaterialsAPI.RateInput;
+
+  /**
+   * A value expressed as a ratio of two units, supplied on create and update
+   * requests.
+   *
+   * A unit price, for example, has a currency as its numerator unit and the unit the
+   * product is bought or sold by as its denominator.
+   */
+  unit_price?: MaterialsAPI.RateInput;
+}
+
+/**
+ * A single page of resources, together with the metadata needed to page through
+ * the rest of the result set.
+ */
+export interface ListPart {
+  /**
+   * Resources in this page.
+   */
+  data: Array<Part>;
+
+  /**
+   * 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 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 {
+  /**
+   * Part ID.
+   */
+  id: string;
+
+  /**
+   * Creation timestamp.
+   */
+  created_at: string;
+
+  /**
+   * An entry in your catalog: something you sell, consume, or build with.
+   */
+  item: ItemsAPI.Item | null;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'part';
+
+  /**
+   * Last updated timestamp.
+   */
+  updated_at: string;
+}
+
+/**
+ * Request to partially update a part.
+ */
+export interface UpdatePartRequest {
+  /**
+   * New free-form description of the part.
+   */
+  description?: string | null;
+
+  /**
+   * New free-form notes about the part.
+   */
+  notes?: string | null;
+
+  /**
+   * 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 PartListParams {
+  /**
+   * Only return parts carrying at least one of these attributes.
+   */
+  attribute_ids?: Array<string>;
+
+  /**
+   * Only return parts belonging to any of these item categories.
+   */
+  category_ids?: Array<string>;
+
+  /**
+   * 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;
+
+  /**
+   * Only return parts created at or before this time.
+   */
+  ends_at?: string;
+
+  /**
+   * 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'
+  >;
+
+  /**
+   * Maximum number of results to return in a single page.
+   */
+  limit?: number;
+
+  /**
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
+   */
+  q?: string;
+
+  /**
+   * Only return parts created at or after this time.
+   */
+  starts_at?: string;
+}
+
+export interface PartRetrieveParams {
+  /**
+   * 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'
+  >;
+}
+
+export interface PartCreateParams {
+  /**
+   * 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`).
+   */
+  category_id: string;
+
+  /**
+   * 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.
+   */
+  sku: string;
+
+  /**
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
+   */
+  include?: Array<
+    'item' | 'item.category' | 'item.unit_value' | 'item.unit_cost' | 'item.burn_rate' | 'item.attributes'
+  >;
+
+  /**
+   * Body param: IDs of existing attributes to link to the part at creation time.
+   */
+  attribute_ids?: Array<string>;
+
+  /**
+   * Body param: Free-form description of the part.
+   */
+  description?: string;
+
+  /**
+   * Body param: Free-form notes about the part.
+   */
+  notes?: string;
+
+  /**
+   * Body param: A value expressed as a ratio of two units, supplied on create and
+   * update requests.
+   *
+   * A unit price, for example, has a currency as its numerator unit and the unit the
+   * product is bought or sold by as its denominator.
+   */
+  unit_cost?: MaterialsAPI.RateInput;
+
+  /**
+   * Body param: A value expressed as a ratio of two units, supplied on create and
+   * update requests.
+   *
+   * A unit price, for example, has a currency as its numerator unit and the unit the
+   * product is bought or sold by as its denominator.
+   */
+  unit_price?: MaterialsAPI.RateInput;
+}
+
+export interface PartUpdateParams {
+  /**
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
+   */
+  include?: Array<
+    'item' | 'item.category' | 'item.unit_value' | 'item.unit_cost' | 'item.burn_rate' | 'item.attributes'
+  >;
+
+  /**
+   * Body param: New free-form description of the part.
+   */
+  description?: string | null;
+
+  /**
+   * Body param: New free-form notes about the part.
+   */
+  notes?: string | null;
+
+  /**
+   * 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.
+   */
+  sku?: string;
+}
+
+Parts.Actions = Actions;
+
+export declare namespace Parts {
+  export {
+    type CreatePartRequest as CreatePartRequest,
+    type ListPart as ListPart,
+    type Part as Part,
+    type UpdatePartRequest as UpdatePartRequest,
+    type PartListParams as PartListParams,
+    type PartRetrieveParams as PartRetrieveParams,
+    type PartCreateParams as PartCreateParams,
+    type PartUpdateParams as PartUpdateParams,
+  };
+
+  export {
+    Actions as Actions,
+    type BulkUpsertPartsRequest as BulkUpsertPartsRequest,
+    type UpsertPartInput as UpsertPartInput,
+    type UpsertPartProperty as UpsertPartProperty,
+    type ActionBulkUpsertParams as ActionBulkUpsertParams,
+  };
+}