@augno/sdk 0.1.9 → 0.7.1

package/src/resources/catalog/units.ts

@@ -11,29 +11,25 @@ import { path } from '../../internal/utils/path';
  */
 export class Units extends APIResource {
   /**
-   * Creates an account-owned unit.
+   * Returns a paginated list of units for the current account, including both
+   * account-owned and global system units.
+   *
+   * This endpoint requires the permission: `units:read`.
    *
    * @example
    * ```ts
-   * const unit = await client.catalog.units.create({
-   *   abbreviation: 'g',
-   *   name: 'Gram',
-   *   offset_denominator: '1',
-   *   offset_numerator: '0',
-   *   ratio_denominator: '1',
-   *   ratio_numerator: '1',
-   *   type: 'mass',
-   * });
+   * const listUnit = await client.catalog.units.list();
    * ```
    */
-  create(params: UnitCreateParams, options?: RequestOptions): APIPromise<Unit> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/catalog/units', { query: { include }, body, ...options });
+  list(query: UnitListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListUnit> {
+    return this._client.get('/v1/catalog/units', { query, ...options });
   }
 
   /**
    * Returns a unit by ID, including both account-owned and global system units.
    *
+   * This endpoint requires the permission: `units:read`.
+   *
    * @example
    * ```ts
    * const unit = await client.catalog.units.retrieve(
@@ -49,13 +45,39 @@ export class Units extends APIResource {
     return this._client.get(path`/v1/catalog/units/${id}`, { query, ...options });
   }
 
+  /**
+   * Creates an account-owned unit.
+   *
+   * This endpoint requires the permission: `units:create`.
+   *
+   * @example
+   * ```ts
+   * const unit = await client.catalog.units.create({
+   *   abbreviation: 'g',
+   *   name: 'Gram',
+   *   offset_denominator: '1',
+   *   offset_numerator: '0',
+   *   ratio_denominator: '1',
+   *   ratio_numerator: '1',
+   *   type: 'mass',
+   * });
+   * ```
+   */
+  create(params: UnitCreateParams, options?: RequestOptions): APIPromise<Unit> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/catalog/units', { query: { include }, body, ...options });
+  }
+
   /**
    * Partially updates an account-owned unit; system units cannot be updated.
    *
+   * This endpoint requires the permission: `units:update`.
+   *
    * @example
    * ```ts
    * const unit = await client.catalog.units.update(
    *   'un_01966263f74a5a0cae356000a1',
+   *   { abbreviation: 'kg', name: 'Kilogram' },
    * );
    * ```
    */
@@ -69,21 +91,12 @@ export class Units extends APIResource {
   }
 
   /**
-   * Returns a paginated list of units for the current account, including both
-   * account-owned and global system units.
+   * Deletes an account-owned unit.
    *
-   * @example
-   * ```ts
-   * const listUnit = await client.catalog.units.list();
-   * ```
-   */
-  list(query: UnitListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListUnit> {
-    return this._client.get('/v1/catalog/units', { query, ...options });
-  }
-
-  /**
-   * Deletes an account-owned unit. Associated unit group memberships are also
-   * removed, and system units cannot be deleted.
+   * Associated unit group memberships are also removed, and system units cannot be
+   * deleted.
+   *
+   * This endpoint requires the permission: `units:delete`.
    *
    * @example
    * ```ts
@@ -103,37 +116,46 @@ export class Units extends APIResource {
 export interface CreateUnitRequest {
   /**
    * Short abbreviation for the unit (e.g. "g").
+   *
+   * Must be unique within the account.
    */
   abbreviation: string;
 
   /**
    * Display name of the unit (e.g. "Gram").
+   *
+   * Must be unique within the account.
    */
   name: string;
 
   /**
-   * Conversion offset denominator, as a decimal string. Must not be zero.
+   * Conversion offset denominator.
+   *
+   * Must not be zero.
    */
   offset_denominator: string;
 
   /**
-   * Conversion offset numerator, as a decimal string.
+   * Conversion offset numerator, used for temperature-like conversions.
    */
   offset_numerator: string;
 
   /**
-   * Conversion ratio denominator relative to the base unit, as a decimal string.
+   * Conversion ratio denominator relative to the base unit.
+   *
    * Must not be zero.
    */
   ratio_denominator: string;
 
   /**
-   * Conversion ratio numerator relative to the base unit, as a decimal string.
+   * Conversion ratio numerator relative to the base unit.
    */
   ratio_numerator: string;
 
   /**
-   * Unit dimension code.
+   * Unit dimension.
+   *
+   * Units can only be converted to other units of the same dimension.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 }
@@ -178,8 +200,10 @@ export interface Unit {
   created_at: string;
 
   /**
-   * Whether this is the base unit for its dimension. Conversion ratios are relative
-   * to this unit.
+   * Whether this is the base unit for its dimension.
+   *
+   * Conversion ratios are relative to this unit. Base units are platform-defined;
+   * account-created units always have this set to `false`.
    */
   is_base_unit: boolean;
 
@@ -194,13 +218,16 @@ export interface Unit {
   object: 'unit';
 
   /**
-   * Conversion offset denominator. Typically 1. Cannot be zero.
+   * Conversion offset denominator.
+   *
+   * Typically 1. Cannot be zero.
    */
   offset_denominator: string;
 
   /**
-   * Conversion offset numerator, used for temperature-like conversions. Zero for
-   * most unit types.
+   * Conversion offset numerator, used for temperature-like conversions.
+   *
+   * Zero for most unit types.
    */
   offset_numerator: string;
 
@@ -211,6 +238,7 @@ export interface Unit {
 
   /**
    * Conversion ratio denominator relative to the base unit in the same dimension.
+   *
    * Cannot be zero.
    */
   ratio_denominator: string;
@@ -221,7 +249,11 @@ export interface Unit {
   ratio_numerator: string;
 
   /**
-   * Unit dimension.
+   * Physical dimension the unit measures, such as mass, volume, or currency.
+   *
+   * A unit can only be converted to another unit of the same dimension. The
+   * `quantity` dimension is for discrete countable items rather than a physical
+   * measure.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
@@ -237,73 +269,135 @@ export interface Unit {
 export interface UpdateUnitRequest {
   /**
    * Short abbreviation for the unit.
+   *
+   * Must be unique within the account.
    */
   abbreviation?: string;
 
   /**
    * Display name of the unit.
+   *
+   * Must be unique within the account.
    */
   name?: string;
 
   /**
-   * Conversion offset denominator, as a decimal string. Must not be zero.
+   * Conversion offset denominator.
+   *
+   * Must not be zero.
    */
   offset_denominator?: string;
 
   /**
-   * Conversion offset numerator, as a decimal string.
+   * Conversion offset numerator, used for temperature-like conversions.
    */
   offset_numerator?: string;
 
   /**
-   * Conversion ratio denominator, as a decimal string. Must not be zero.
+   * Conversion ratio denominator relative to the base unit.
+   *
+   * Must not be zero.
    */
   ratio_denominator?: string;
 
   /**
-   * Conversion ratio numerator, as a decimal string.
+   * Conversion ratio numerator relative to the base unit.
    */
   ratio_numerator?: string;
 }
 
 export interface UnitDeleteResponse {}
 
+export interface UnitListParams {
+  /**
+   * 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;
+
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'owner' | 'owner.account'>;
+
+  /**
+   * 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;
+
+  /**
+   * Filter by unit dimension.
+   */
+  type?: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
+
+  /**
+   * Return only units that belong to at least one of the given unit groups.
+   */
+  unit_group_ids?: Array<string>;
+}
+
+export interface UnitRetrieveParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'owner' | 'owner.account'>;
+}
+
 export interface UnitCreateParams {
   /**
    * Body param: Short abbreviation for the unit (e.g. "g").
+   *
+   * Must be unique within the account.
    */
   abbreviation: string;
 
   /**
    * Body param: Display name of the unit (e.g. "Gram").
+   *
+   * Must be unique within the account.
    */
   name: string;
 
   /**
-   * Body param: Conversion offset denominator, as a decimal string. Must not be
-   * zero.
+   * Body param: Conversion offset denominator.
+   *
+   * Must not be zero.
    */
   offset_denominator: string;
 
   /**
-   * Body param: Conversion offset numerator, as a decimal string.
+   * Body param: Conversion offset numerator, used for temperature-like conversions.
    */
   offset_numerator: string;
 
   /**
-   * Body param: Conversion ratio denominator relative to the base unit, as a decimal
-   * string. Must not be zero.
+   * Body param: Conversion ratio denominator relative to the base unit.
+   *
+   * Must not be zero.
    */
   ratio_denominator: string;
 
   /**
-   * Body param: Conversion ratio numerator relative to the base unit, as a decimal
-   * string.
+   * Body param: Conversion ratio numerator relative to the base unit.
    */
   ratio_numerator: string;
 
   /**
-   * Body param: Unit dimension code.
+   * Body param: Unit dimension.
+   *
+   * Units can only be converted to other units of the same dimension.
    */
   type: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
 
@@ -314,14 +408,6 @@ export interface UnitCreateParams {
   include?: Array<'owner' | 'owner.account'>;
 }
 
-export interface UnitRetrieveParams {
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<'owner' | 'owner.account'>;
-}
-
 export interface UnitUpdateParams {
   /**
    * Query param: Sub-objects to expand in the response. When omitted, sub-objects
@@ -331,69 +417,43 @@ export interface UnitUpdateParams {
 
   /**
    * Body param: Short abbreviation for the unit.
+   *
+   * Must be unique within the account.
    */
   abbreviation?: string;
 
   /**
    * Body param: Display name of the unit.
+   *
+   * Must be unique within the account.
    */
   name?: string;
 
   /**
-   * Body param: Conversion offset denominator, as a decimal string. Must not be
-   * zero.
+   * Body param: Conversion offset denominator.
+   *
+   * Must not be zero.
    */
   offset_denominator?: string;
 
   /**
-   * Body param: Conversion offset numerator, as a decimal string.
+   * Body param: Conversion offset numerator, used for temperature-like conversions.
    */
   offset_numerator?: string;
 
   /**
-   * Body param: Conversion ratio denominator, as a decimal string. Must not be zero.
+   * Body param: Conversion ratio denominator relative to the base unit.
+   *
+   * Must not be zero.
    */
   ratio_denominator?: string;
 
   /**
-   * Body param: Conversion ratio numerator, as a decimal string.
+   * Body param: Conversion ratio numerator relative to the base unit.
    */
   ratio_numerator?: string;
 }
 
-export interface UnitListParams {
-  /**
-   * Cursor token used to retrieve the next or previous page of results.
-   */
-  cursor?: string;
-
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<'owner' | 'owner.account'>;
-
-  /**
-   * Maximum number of results per page (default: 100, max: 1000).
-   */
-  limit?: number;
-
-  /**
-   * Search query used to filter results.
-   */
-  q?: string;
-
-  /**
-   * Filter by unit dimension code.
-   */
-  type?: 'currency' | 'quantity' | 'time' | 'mass' | 'volume' | 'length' | 'temperature' | 'area';
-
-  /**
-   * Filter by unit group membership.
-   */
-  unit_group_ids?: Array<string>;
-}
-
 export declare namespace Units {
   export {
     type CreateUnitRequest as CreateUnitRequest,
@@ -401,9 +461,9 @@ export declare namespace Units {
     type Unit as Unit,
     type UpdateUnitRequest as UpdateUnitRequest,
     type UnitDeleteResponse as UnitDeleteResponse,
-    type UnitCreateParams as UnitCreateParams,
+    type UnitListParams as UnitListParams,
     type UnitRetrieveParams as UnitRetrieveParams,
+    type UnitCreateParams as UnitCreateParams,
     type UnitUpdateParams as UnitUpdateParams,
-    type UnitListParams as UnitListParams,
   };
 }

package/src/resources/core/addresses/actions.ts

@@ -89,7 +89,7 @@ export interface ValidateAddressRequest {
   city: string;
 
   /**
-   * Country name or code.
+   * Country name or two-letter country code (for example `United States` or `US`).
    */
   country: string;
 
@@ -119,7 +119,10 @@ export interface ValidatedAddress {
   components: AddressComponents | null;
 
   /**
-   * Formatted address from the validation service.
+   * Formatted, single-line address as standardized by the validation service.
+   *
+   * The validation service may omit this regardless of `status`, so it can be absent
+   * even for a `valid` address.
    */
   formatted_address: string | null;
 
@@ -129,12 +132,16 @@ export interface ValidatedAddress {
   object: 'validated_address';
 
   /**
-   * Address validation status.
+   * Whether the address could be validated.
    */
   status: 'valid' | 'invalid';
 
   /**
-   * Validation messages for issues found.
+   * Human-readable messages describing issues found during validation.
+   *
+   * May be non-empty even when `status` is `valid`, for example when components were
+   * inferred or replaced with standardized values. Empty when no issues were
+   * reported.
    */
   validation_messages: Array<string>;
 }
@@ -151,7 +158,7 @@ export interface ActionValidateParams {
   city: string;
 
   /**
-   * Country name or code.
+   * Country name or two-letter country code (for example `United States` or `US`).
    */
   country: string;
 

package/src/resources/core/addresses/addresses.ts

@@ -90,12 +90,15 @@ export interface ListAddressSuggestion {
 
 export interface AddressRetrieveSuggestionsParams {
   /**
-   * Autocomplete input text.
+   * Partial address text to generate suggestions for.
    */
   input: string;
 
   /**
-   * Session token for grouping autocomplete requests.
+   * Opaque token that groups a series of related autocomplete requests into a single
+   * session.
+   *
+   * Reuse the same token for each keystroke of one address entry.
    */
   session_token?: string;
 }