@augno/sdk 0.1.9 → 0.7.1

package/src/resources/catalog/properties/attributes.ts

@@ -11,28 +11,31 @@ import { path } from '../../../internal/utils/path';
  */
 export class Attributes extends APIResource {
   /**
-   * Creates an attribute under a property.
+   * Returns a paginated list of attributes for a property.
+   *
+   * This endpoint requires the permission: `properties:read`.
    *
    * @example
    * ```ts
-   * const attribute =
-   *   await client.catalog.properties.attributes.create(
+   * const listAttribute =
+   *   await client.catalog.properties.attributes.list(
    *     'pp_01e21344878064372f69e67093',
-   *     { value: 'Red' },
    *   );
    * ```
    */
-  create(
+  list(
     propertyID: string,
-    body: AttributeCreateParams,
+    query: AttributeListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<PropertiesAPI.Attribute> {
-    return this._client.post(path`/v1/catalog/properties/${propertyID}/attributes`, { body, ...options });
+  ): APIPromise<PropertiesAPI.ListAttribute> {
+    return this._client.get(path`/v1/catalog/properties/${propertyID}/attributes`, { query, ...options });
   }
 
   /**
    * Returns an attribute by ID within a property.
    *
+   * This endpoint requires the permission: `properties:read`.
+   *
    * @example
    * ```ts
    * const attribute =
@@ -51,15 +54,46 @@ export class Attributes extends APIResource {
     return this._client.get(path`/v1/catalog/properties/${property_id}/attributes/${id}`, options);
   }
 
+  /**
+   * Creates an attribute under a property.
+   *
+   * This endpoint requires the permission: `properties:create`.
+   *
+   * @example
+   * ```ts
+   * const attribute =
+   *   await client.catalog.properties.attributes.create(
+   *     'pp_01e21344878064372f69e67093',
+   *     {
+   *       value: 'Red',
+   *       color: 'red',
+   *       sort_order: 1,
+   *     },
+   *   );
+   * ```
+   */
+  create(
+    propertyID: string,
+    body: AttributeCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<PropertiesAPI.Attribute> {
+    return this._client.post(path`/v1/catalog/properties/${propertyID}/attributes`, { body, ...options });
+  }
+
   /**
    * Partially updates an attribute.
    *
+   * This endpoint requires the permission: `properties:update`.
+   *
    * @example
    * ```ts
    * const attribute =
    *   await client.catalog.properties.attributes.update(
    *     'at_01c9493ec0c46bb0ed12708ae4',
-   *     { property_id: 'pp_01e21344878064372f69e67093' },
+   *     {
+   *       property_id: 'pp_01e21344878064372f69e67093',
+   *       value: 'Blue',
+   *     },
    *   );
    * ```
    */
@@ -75,28 +109,14 @@ export class Attributes extends APIResource {
     });
   }
 
-  /**
-   * Returns a paginated list of attributes for a property.
-   *
-   * @example
-   * ```ts
-   * const listAttribute =
-   *   await client.catalog.properties.attributes.list(
-   *     'pp_01e21344878064372f69e67093',
-   *   );
-   * ```
-   */
-  list(
-    propertyID: string,
-    query: AttributeListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<PropertiesAPI.ListAttribute> {
-    return this._client.get(path`/v1/catalog/properties/${propertyID}/attributes`, { query, ...options });
-  }
-
   /**
    * Deletes an attribute from a property.
    *
+   * Remaining attributes in the property are shifted so their sort orders stay
+   * contiguous.
+   *
+   * This endpoint requires the permission: `properties:delete`.
+   *
    * @example
    * ```ts
    * const attribute =
@@ -121,17 +141,28 @@ export class Attributes extends APIResource {
  */
 export interface CreateAttributeRequest {
   /**
-   * Attribute value.
+   * The selectable value this attribute represents, such as `Red`.
+   *
+   * Must be unique across all attributes in the account, not just within the
+   * property. Leading and trailing whitespace is trimmed.
    */
   value: string;
 
   /**
-   * Color code. Randomly assigned if not provided.
+   * Swatch color used to display this attribute in the UI.
+   *
+   * When omitted, one of the nine named colors (everything except `default`) is
+   * assigned at random.
    */
   color?: 'blue' | 'brown' | 'default' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'yellow';
 
   /**
-   * Display order. Defaults to last position if not provided.
+   * Position of the new attribute relative to its siblings within the property,
+   * starting at `1`.
+   *
+   * Must be at most the property's current attribute count plus one; siblings at or
+   * after this position are shifted one position later. Defaults to the last
+   * position if not provided.
    */
   sort_order?: number;
 }
@@ -141,38 +172,51 @@ export interface CreateAttributeRequest {
  */
 export interface UpdateAttributeRequest {
   /**
-   * Color code.
+   * Swatch color used to display this attribute in the UI.
    */
   color?: 'blue' | 'brown' | 'default' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'yellow';
 
   /**
-   * Display order. Must be a positive integer.
+   * New position of this attribute relative to its siblings within the property,
+   * starting at `1`.
+   *
+   * Must be at most the property's current attribute count; the attributes between
+   * the old and new positions shift to make room.
    */
   sort_order?: number;
 
   /**
-   * Attribute value.
+   * The selectable value this attribute represents, such as `Red`.
+   *
+   * Must be non-blank and unique across all attributes in the account, not just
+   * within the property.
    */
   value?: string;
 }
 
 export interface AttributeDeleteResponse {}
 
-export interface AttributeCreateParams {
+export interface AttributeListParams {
   /**
-   * Attribute value.
+   * 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.
    */
-  value: string;
+  cursor?: string;
 
   /**
-   * Color code. Randomly assigned if not provided.
+   * Maximum number of results to return in a single page.
    */
-  color?: 'blue' | 'brown' | 'default' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'yellow';
+  limit?: number;
 
   /**
-   * Display order. Defaults to last position if not provided.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
-  sort_order?: number;
+  q?: string;
 }
 
 export interface AttributeRetrieveParams {
@@ -182,43 +226,61 @@ export interface AttributeRetrieveParams {
   property_id: string;
 }
 
-export interface AttributeUpdateParams {
+export interface AttributeCreateParams {
   /**
-   * Path param: Property ID.
+   * The selectable value this attribute represents, such as `Red`.
+   *
+   * Must be unique across all attributes in the account, not just within the
+   * property. Leading and trailing whitespace is trimmed.
    */
-  property_id: string;
+  value: string;
 
   /**
-   * Body param: Color code.
+   * Swatch color used to display this attribute in the UI.
+   *
+   * When omitted, one of the nine named colors (everything except `default`) is
+   * assigned at random.
    */
   color?: 'blue' | 'brown' | 'default' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'yellow';
 
   /**
-   * Body param: Display order. Must be a positive integer.
+   * Position of the new attribute relative to its siblings within the property,
+   * starting at `1`.
+   *
+   * Must be at most the property's current attribute count plus one; siblings at or
+   * after this position are shifted one position later. Defaults to the last
+   * position if not provided.
    */
   sort_order?: number;
+}
 
+export interface AttributeUpdateParams {
   /**
-   * Body param: Attribute value.
+   * Path param: Property ID.
    */
-  value?: string;
-}
+  property_id: string;
 
-export interface AttributeListParams {
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: Swatch color used to display this attribute in the UI.
    */
-  cursor?: string;
+  color?: 'blue' | 'brown' | 'default' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'yellow';
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Body param: New position of this attribute relative to its siblings within the
+   * property, starting at `1`.
+   *
+   * Must be at most the property's current attribute count; the attributes between
+   * the old and new positions shift to make room.
    */
-  limit?: number;
+  sort_order?: number;
 
   /**
-   * Search query used to filter results.
+   * Body param: The selectable value this attribute represents, such as `Red`.
+   *
+   * Must be non-blank and unique across all attributes in the account, not just
+   * within the property.
    */
-  q?: string;
+  value?: string;
 }
 
 export interface AttributeDeleteParams {
@@ -233,10 +295,10 @@ export declare namespace Attributes {
     type CreateAttributeRequest as CreateAttributeRequest,
     type UpdateAttributeRequest as UpdateAttributeRequest,
     type AttributeDeleteResponse as AttributeDeleteResponse,
-    type AttributeCreateParams as AttributeCreateParams,
+    type AttributeListParams as AttributeListParams,
     type AttributeRetrieveParams as AttributeRetrieveParams,
+    type AttributeCreateParams as AttributeCreateParams,
     type AttributeUpdateParams as AttributeUpdateParams,
-    type AttributeListParams as AttributeListParams,
     type AttributeDeleteParams as AttributeDeleteParams,
   };
 }

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

@@ -5,10 +5,10 @@ export {
   type CreateAttributeRequest,
   type UpdateAttributeRequest,
   type AttributeDeleteResponse,
-  type AttributeCreateParams,
+  type AttributeListParams,
   type AttributeRetrieveParams,
+  type AttributeCreateParams,
   type AttributeUpdateParams,
-  type AttributeListParams,
   type AttributeDeleteParams,
 } from './attributes';
 export {
@@ -20,8 +20,8 @@ export {
   type Property,
   type UpdatePropertyRequest,
   type PropertyDeleteResponse,
-  type PropertyCreateParams,
+  type PropertyListParams,
   type PropertyRetrieveParams,
+  type PropertyCreateParams,
   type PropertyUpdateParams,
-  type PropertyListParams,
 } from './properties';

package/src/resources/catalog/properties/properties.ts

@@ -25,23 +25,27 @@ export class Properties extends APIResource {
   attributes: AttributesAPI.Attributes = new AttributesAPI.Attributes(this._client);
 
   /**
-   * Creates a property.
+   * Returns a paginated list of properties for the target account.
+   *
+   * This endpoint requires the permission: `properties:read`.
    *
    * @example
    * ```ts
-   * const property = await client.catalog.properties.create({
-   *   name: 'Color',
-   * });
+   * const listProperty = await client.catalog.properties.list();
    * ```
    */
-  create(params: PropertyCreateParams, options?: RequestOptions): APIPromise<Property> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/properties', { query: { include }, body, ...options });
+  list(
+    query: PropertyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ListProperty> {
+    return this._client.get('/v1/catalog/properties', { query, ...options });
   }
 
   /**
    * Returns a property by ID.
    *
+   * This endpoint requires the permission: `properties:read`.
+   *
    * @example
    * ```ts
    * const property = await client.catalog.properties.retrieve(
@@ -57,13 +61,33 @@ export class Properties extends APIResource {
     return this._client.get(path`/v1/catalog/properties/${id}`, { query, ...options });
   }
 
+  /**
+   * Creates a property.
+   *
+   * This endpoint requires the permission: `properties:create`.
+   *
+   * @example
+   * ```ts
+   * const property = await client.catalog.properties.create({
+   *   name: 'Color',
+   * });
+   * ```
+   */
+  create(params: PropertyCreateParams, options?: RequestOptions): APIPromise<Property> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/properties', { query: { include }, body, ...options });
+  }
+
   /**
    * Partially updates a property.
    *
+   * This endpoint requires the permission: `properties:update`.
+   *
    * @example
    * ```ts
    * const property = await client.catalog.properties.update(
    *   'pp_01e21344878064372f69e67093',
+   *   { name: 'Size' },
    * );
    * ```
    */
@@ -76,24 +100,11 @@ export class Properties extends APIResource {
     return this._client.patch(path`/v1/catalog/properties/${id}`, { query: { include }, body, ...options });
   }
 
-  /**
-   * Returns a paginated list of properties for the target account.
-   *
-   * @example
-   * ```ts
-   * const listProperty = await client.catalog.properties.list();
-   * ```
-   */
-  list(
-    query: PropertyListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ListProperty> {
-    return this._client.get('/v1/catalog/properties', { query, ...options });
-  }
-
   /**
    * Deletes a property and all associated attributes.
    *
+   * This endpoint requires the permission: `properties:delete`.
+   *
    * @example
    * ```ts
    * const property = await client.catalog.properties.delete(
@@ -107,7 +118,9 @@ export class Properties extends APIResource {
 }
 
 /**
- * Value option within a property.
+ * A selectable value within a property, such as `Red` for a `Color` property.
+ *
+ * Attributes are assigned to items to classify them.
  */
 export interface Attribute {
   /**
@@ -116,7 +129,10 @@ export interface Attribute {
   id: string;
 
   /**
-   * Color code.
+   * Swatch color used to display this attribute in the UI.
+   *
+   * The named colors are arbitrary display choices; `default` is a neutral fallback
+   * used when no specific swatch applies.
    */
   color: 'blue' | 'brown' | 'default' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'yellow';
 
@@ -131,12 +147,19 @@ export interface Attribute {
   object: 'attribute';
 
   /**
-   * Property that groups attributes.
+   * A named characteristic used to classify items, such as `Color` or `Size`.
+   *
+   * Each property defines a set of attributes — the selectable values (e.g. `Red`,
+   * `Blue`) that can be assigned to items.
    */
   property: Property | null;
 
   /**
-   * Display order.
+   * Position of this attribute relative to its siblings within the property,
+   * starting at `1`.
+   *
+   * Positions are kept contiguous: creating, reordering, or deleting an attribute
+   * automatically shifts its siblings.
    */
   sort_order: number;
 
@@ -146,7 +169,8 @@ export interface Attribute {
   updated_at: string;
 
   /**
-   * Attribute value.
+   * The selectable value this attribute represents, such as `Red` for a `Color`
+   * property or `Large` for a `Size` property.
    */
   value: string;
 }
@@ -156,7 +180,7 @@ export interface Attribute {
  */
 export interface CreatePropertyRequest {
   /**
-   * Name.
+   * Display name of the property, such as `Color` or `Size`.
    */
   name: string;
 }
@@ -202,7 +226,10 @@ export interface ListProperty {
 }
 
 /**
- * Property that groups attributes.
+ * A named characteristic used to classify items, such as `Color` or `Size`.
+ *
+ * Each property defines a set of attributes — the selectable values (e.g. `Red`,
+ * `Blue`) that can be assigned to items.
  */
 export interface Property {
   /**
@@ -221,7 +248,7 @@ export interface Property {
   created_at: string;
 
   /**
-   * Display name.
+   * Display name of the property, such as `Color` or `Size`.
    */
   name: string;
 
@@ -241,68 +268,74 @@ export interface Property {
  */
 export interface UpdatePropertyRequest {
   /**
-   * Name.
+   * Display name of the property, such as `Color` or `Size`.
    */
   name?: string;
 }
 
 export interface PropertyDeleteResponse {}
 
-export interface PropertyCreateParams {
+export interface PropertyListParams {
   /**
-   * Body param: Name.
+   * 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.
    */
-  name: string;
+  cursor?: string;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
   include?: Array<'attributes'>;
-}
 
-export interface PropertyRetrieveParams {
   /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
+   * Maximum number of results to return in a single page.
    */
-  include?: Array<'attributes'>;
-}
+  limit?: number;
 
-export interface PropertyUpdateParams {
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
-  include?: Array<'attributes'>;
+  q?: string;
+}
 
+export interface PropertyRetrieveParams {
   /**
-   * Body param: Name.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
-  name?: string;
+  include?: Array<'attributes'>;
 }
 
-export interface PropertyListParams {
+export interface PropertyCreateParams {
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: Display name of the property, such as `Color` or `Size`.
    */
-  cursor?: string;
+  name: string;
 
   /**
-   * 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<'attributes'>;
+}
 
+export interface PropertyUpdateParams {
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
-  limit?: number;
+  include?: Array<'attributes'>;
 
   /**
-   * Search query used to filter results.
+   * Body param: Display name of the property, such as `Color` or `Size`.
    */
-  q?: string;
+  name?: string;
 }
 
 Properties.Attributes = Attributes;
@@ -316,10 +349,10 @@ export declare namespace Properties {
     type Property as Property,
     type UpdatePropertyRequest as UpdatePropertyRequest,
     type PropertyDeleteResponse as PropertyDeleteResponse,
-    type PropertyCreateParams as PropertyCreateParams,
+    type PropertyListParams as PropertyListParams,
     type PropertyRetrieveParams as PropertyRetrieveParams,
+    type PropertyCreateParams as PropertyCreateParams,
     type PropertyUpdateParams as PropertyUpdateParams,
-    type PropertyListParams as PropertyListParams,
   };
 
   export {
@@ -327,10 +360,10 @@ export declare namespace Properties {
     type CreateAttributeRequest as CreateAttributeRequest,
     type UpdateAttributeRequest as UpdateAttributeRequest,
     type AttributeDeleteResponse as AttributeDeleteResponse,
-    type AttributeCreateParams as AttributeCreateParams,
+    type AttributeListParams as AttributeListParams,
     type AttributeRetrieveParams as AttributeRetrieveParams,
+    type AttributeCreateParams as AttributeCreateParams,
     type AttributeUpdateParams as AttributeUpdateParams,
-    type AttributeListParams as AttributeListParams,
     type AttributeDeleteParams as AttributeDeleteParams,
   };
 }

package/src/resources/catalog/unit-groups/index.ts

@@ -10,19 +10,19 @@ export {
   type UnitGroupUnit,
   type UpdateUnitGroupRequest,
   type UnitGroupDeleteResponse,
-  type UnitGroupCreateParams,
+  type UnitGroupListParams,
   type UnitGroupRetrieveParams,
+  type UnitGroupCreateParams,
   type UnitGroupUpdateParams,
-  type UnitGroupListParams,
 } from './unit-groups';
 export {
   Units,
   type CreateUnitGroupUnitRequest,
   type UpdateUnitGroupUnitRequest,
   type UnitDeleteResponse,
-  type UnitCreateParams,
+  type UnitListParams,
   type UnitRetrieveParams,
+  type UnitCreateParams,
   type UnitUpdateParams,
-  type UnitListParams,
   type UnitDeleteParams,
 } from './units';