@augno/sdk 0.1.9 → 0.7.0

package/src/resources/auth/api-keys/api-keys.ts

@@ -13,28 +13,6 @@ import { path } from '../../../internal/utils/path';
 export class APIKeys extends APIResource {
   actions: ActionsAPI.Actions = new ActionsAPI.Actions(this._client);
 
-  /**
-   * Creates an [API key](https://docs.augno.com/api/api-keys) to authenticate API
-   * requests.
-   *
-   * The secret key is returned once and cannot be retrieved later, so you should
-   * store it securely. We provide some
-   * [recommendations](https://docs.augno.com/api/managing-api-keys) on how you can
-   * manage your API keys.
-   *
-   * @example
-   * ```ts
-   * const createdAPIKey = await client.auth.apiKeys.create({
-   *   name: 'Production API Key',
-   *   role_id: 'rl_01c16d2eb637c0d1f3a372937c',
-   * });
-   * ```
-   */
-  create(params: APIKeyCreateParams, options?: RequestOptions): APIPromise<CreatedAPIKey> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/auth/api-keys', { query: { include }, body, ...options });
-  }
-
   /**
    * Returns [API key](https://docs.augno.com/api/api-keys) metadata by ID.
    *
@@ -65,10 +43,34 @@ export class APIKeys extends APIResource {
     return this._client.get('/v1/auth/api-keys', { query, ...options });
   }
 
+  /**
+   * Creates an [API key](https://docs.augno.com/api/api-keys) to authenticate API
+   * requests.
+   *
+   * The secret key is returned once and cannot be retrieved later, so you should
+   * store it securely. We provide some
+   * [recommendations](https://docs.augno.com/api/managing-api-keys) on how you can
+   * manage your API keys.
+   *
+   * @example
+   * ```ts
+   * const createdAPIKey = await client.auth.apiKeys.create({
+   *   name: 'Production API Key',
+   *   role_id: 'rl_01c16d2eb637c0d1f3a372937c',
+   * });
+   * ```
+   */
+  create(params: APIKeyCreateParams, options?: RequestOptions): APIPromise<CreatedAPIKey> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/auth/api-keys', { query: { include }, body, ...options });
+  }
+
   /**
    * Revokes an [API key](https://docs.augno.com/api/api-keys).
    *
-   * Revoked API keys will be unable to be used to authenticate requests.
+   * Revocation takes effect immediately and cannot be undone; revoked keys can no
+   * longer be used to authenticate requests. To replace a key without losing access,
+   * use Rotate API Key instead.
    *
    * @example
    * ```ts
@@ -83,7 +85,7 @@ export class APIKeys extends APIResource {
 }
 
 /**
- * Account with optional branding and portal sub-resources.
+ * A customer account, including its branding and customer portal sub-resources.
  */
 export interface Account {
   /**
@@ -102,12 +104,14 @@ export interface Account {
   created_at: string;
 
   /**
-   * Address with associated geolocation.
+   * A saved address that can be used for billing and shipping on sales orders,
+   * invoices, and shipments.
    */
   default_billing_address: Address | null;
 
   /**
-   * Address with associated geolocation.
+   * A saved address that can be used for billing and shipping on sales orders,
+   * invoices, and shipments.
    */
   default_shipping_address: Address | null;
 
@@ -217,7 +221,9 @@ export interface AccountPortal {
   object: 'account_portal';
 
   /**
-   * Portal slug.
+   * URL slug that identifies the account's customer portal.
+   *
+   * Unique across all accounts.
    */
   slug: string;
 
@@ -228,7 +234,8 @@ export interface AccountPortal {
 }
 
 /**
- * Address with associated geolocation.
+ * A saved address that can be used for billing and shipping on sales orders,
+ * invoices, and shipments.
  */
 export interface Address {
   /**
@@ -247,7 +254,7 @@ export interface Address {
   email: string | null;
 
   /**
-   * Geolocation sub-resource.
+   * The street-level location details of an address.
    */
   geolocation: Geolocation | null;
 
@@ -268,6 +275,10 @@ export interface Address {
 
   /**
    * Address type.
+   *
+   * - `standard`: a normal shipping or billing address.
+   * - `drop_ship`: an address an order is shipped to directly, typically a third
+   *   party or end customer rather than the account itself.
    */
   type: 'standard' | 'drop_ship';
 
@@ -278,7 +289,7 @@ export interface Address {
 }
 
 /**
- * API key resource.
+ * An API key used to authenticate requests to the Augno API.
  */
 export interface APIKey {
   /**
@@ -292,12 +303,17 @@ export interface APIKey {
   created_at: string;
 
   /**
-   * Expiration timestamp.
+   * When the key expires and stops authenticating.
+   *
+   * `null` if the key never expires.
    */
   expires_at: string | null;
 
   /**
-   * Last used timestamp.
+   * When the key was last used to authenticate a request.
+   *
+   * Updated at most once every 24 hours, so it may lag the key's most recent use.
+   * `null` if the key has never been used.
    */
   last_used_at: string | null;
 
@@ -313,16 +329,24 @@ export interface APIKey {
 
   /**
    * Redacted key value safe for display.
+   *
+   * The key's prefix followed by its last four characters, e.g.
+   * `aug_sk_prod_****hjt4`.
    */
   redacted_value: string;
 
   /**
-   * Revocation timestamp.
+   * When the key's revocation takes effect.
+   *
+   * A future timestamp means revocation was scheduled (for example, during rotation)
+   * and the key continues to authenticate requests until that time. `null` if the
+   * key has not been revoked.
    */
   revoked_at: string | null;
 
   /**
-   * Role resource.
+   * A named set of permissions that can be assigned to users to control what they
+   * can access.
    */
   role: Role | null;
 
@@ -342,12 +366,16 @@ export interface CreateAPIKeyRequest {
   name: string;
 
   /**
-   * Role ID assigned to the API key.
+   * ID of the role to assign to the API key.
+   *
+   * The role determines the permissions of requests authenticated with the key.
    */
   role_id: string;
 
   /**
-   * Expiration timestamp. If not set, the key does not expire.
+   * When the key expires and stops authenticating requests.
+   *
+   * If omitted, the key never expires.
    */
   expires_at?: string;
 }
@@ -357,12 +385,14 @@ export interface CreateAPIKeyRequest {
  */
 export interface CreatedAPIKey {
   /**
-   * API key resource.
+   * An API key used to authenticate requests to the Augno API.
    */
   api_key_info: APIKey;
 
   /**
-   * Full secret value. Returned once and cannot be retrieved later. Learn more about
+   * Full secret value.
+   *
+   * Returned once and cannot be retrieved later. Learn more about
    * [managing your API keys](https://docs.augno.com/api/managing-api-keys).
    */
   api_key_secret: string;
@@ -374,7 +404,7 @@ export interface CreatedAPIKey {
 }
 
 /**
- * Geolocation sub-resource.
+ * The street-level location details of an address.
  */
 export interface Geolocation {
   /**
@@ -443,7 +473,7 @@ export interface ListAPIKey {
  */
 export interface Owner {
   /**
-   * Account with optional branding and portal sub-resources.
+   * A customer account, including its branding and customer portal sub-resources.
    */
   account: Account | null;
 
@@ -453,8 +483,12 @@ export interface Owner {
   object: 'owner';
 
   /**
-   * The owner type: "system" for platform defaults, "account" for account-owned
-   * resources.
+   * Owner type, identifying where the resource came from.
+   *
+   * - `system`: a platform-provided default shared across all accounts; not
+   *   editable.
+   * - `account`: created and owned by a specific account; the `account` field
+   *   identifies which.
    */
   type: 'system' | 'account';
 }
@@ -474,18 +508,23 @@ export interface PageInfo {
   has_prev_page: boolean;
 
   /**
-   * URL to fetch the next page, `null` if no more pages.
+   * Relative URL that fetches the next page of results.
+   *
+   * `null` when the last page has been reached.
    */
   next_page_url: string | null;
 
   /**
-   * URL to fetch the previous page, `null` if on the first page.
+   * Relative URL that fetches the previous page of results.
+   *
+   * `null` while on the first page.
    */
   previous_page_url: string | null;
 }
 
 /**
- * Role resource.
+ * A named set of permissions that can be assigned to users to control what they
+ * can access.
  */
 export interface Role {
   /**
@@ -499,7 +538,7 @@ export interface Role {
   created_at: string;
 
   /**
-   * Display name.
+   * Display name, unique within the account.
    */
   name: string;
 
@@ -514,16 +553,24 @@ export interface Role {
   owner: Owner | null;
 
   /**
-   * Permissions in `{domain}:{action}` format.
+   * Permissions granted by this role, in `{domain}:{action}` format, such as
+   * `customers:read`.
    */
   permissions: Array<string> | null;
 
   /**
-   * Role type code.
+   * The kind of role.
+   *
+   * The role's type is sometimes used to gate special behaviors and to restrict some
+   * actions to only certain types of roles. For example, only roles with the type
+   * `admin` can create and manage API keys.
    *
-   * The role's type is sometimes used to gate special behaviors in the frontend and
-   * to restrict some actions to only certain types of roles. For example, only roles
-   * with the type `admin` can create and manage API keys.
+   * - `admin`: full administrative access, including managing API keys.
+   * - `user`: a custom role tailored to a specific need (its permissions are defined
+   *   explicitly). Roles created through the API always have this type.
+   * - `scanner`: a role for scanning-station operators.
+   * - `sales_rep`: a role for sales representatives.
+   * - `agent`: a role assigned to an automated agent rather than a person.
    */
   type: 'admin' | 'user' | 'scanner' | 'sales_rep' | 'agent';
 
@@ -535,29 +582,6 @@ export interface Role {
 
 export interface APIKeyDeleteResponse {}
 
-export interface APIKeyCreateParams {
-  /**
-   * Body param: Human-readable name for the API key.
-   */
-  name: string;
-
-  /**
-   * Body param: Role ID assigned to the API key.
-   */
-  role_id: string;
-
-  /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
-   */
-  include?: Array<'role' | 'role.permissions'>;
-
-  /**
-   * Body param: Expiration timestamp. If not set, the key does not expire.
-   */
-  expires_at?: string;
-}
-
 export interface APIKeyRetrieveParams {
   /**
    * Sub-objects to expand in the response. When omitted, sub-objects are returned as
@@ -568,7 +592,11 @@ export interface APIKeyRetrieveParams {
 
 export interface APIKeyListParams {
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * 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;
 
@@ -579,21 +607,57 @@ export interface APIKeyListParams {
   include?: Array<'role' | 'role.permissions'>;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Maximum number of results to return in a single page.
    */
   limit?: number;
 
   /**
-   * Search query used to filter results.
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
    */
   q?: string;
 
   /**
    * API key statuses to filter by.
+   *
+   * - `active`: the key can be used to authenticate requests.
+   * - `expired`: the key passed its expiration time and can no longer authenticate
+   *   requests.
+   * - `revoked`: the key was revoked and can no longer authenticate requests.
+   *
+   * When omitted, keys of every status are returned.
    */
   statuses?: Array<'active' | 'expired' | 'revoked'>;
 }
 
+export interface APIKeyCreateParams {
+  /**
+   * Body param: Human-readable name for the API key.
+   */
+  name: string;
+
+  /**
+   * Body param: ID of the role to assign to the API key.
+   *
+   * The role determines the permissions of requests authenticated with the key.
+   */
+  role_id: string;
+
+  /**
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
+   */
+  include?: Array<'role' | 'role.permissions'>;
+
+  /**
+   * Body param: When the key expires and stops authenticating requests.
+   *
+   * If omitted, the key never expires.
+   */
+  expires_at?: string;
+}
+
 APIKeys.Actions = Actions;
 
 export declare namespace APIKeys {
@@ -611,9 +675,9 @@ export declare namespace APIKeys {
     type PageInfo as PageInfo,
     type Role as Role,
     type APIKeyDeleteResponse as APIKeyDeleteResponse,
-    type APIKeyCreateParams as APIKeyCreateParams,
     type APIKeyRetrieveParams as APIKeyRetrieveParams,
     type APIKeyListParams as APIKeyListParams,
+    type APIKeyCreateParams as APIKeyCreateParams,
   };
 
   export {

package/src/resources/auth/api-keys/index.ts

@@ -15,8 +15,8 @@ export {
   type PageInfo,
   type Role,
   type APIKeyDeleteResponse,
-  type APIKeyCreateParams,
   type APIKeyRetrieveParams,
   type APIKeyListParams,
+  type APIKeyCreateParams,
 } from './api-keys';
 export { Actions, type RotateAPIKeyRequest, type ActionRotateParams } from './actions';

package/src/resources/auth/auth.ts

@@ -44,8 +44,8 @@ export declare namespace Auth {
     type PageInfo as PageInfo,
     type Role as Role,
     type APIKeyDeleteResponse as APIKeyDeleteResponse,
-    type APIKeyCreateParams as APIKeyCreateParams,
     type APIKeyRetrieveParams as APIKeyRetrieveParams,
     type APIKeyListParams as APIKeyListParams,
+    type APIKeyCreateParams as APIKeyCreateParams,
   };
 }

package/src/resources/auth/index.ts

@@ -15,8 +15,8 @@ export {
   type PageInfo,
   type Role,
   type APIKeyDeleteResponse,
-  type APIKeyCreateParams,
   type APIKeyRetrieveParams,
   type APIKeyListParams,
+  type APIKeyCreateParams,
 } from './api-keys/index';
 export { Auth } from './auth';

package/src/resources/catalog/catalog.ts

@@ -157,10 +157,10 @@ export declare namespace Catalog {
     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,
   };
 
   export {
@@ -173,10 +173,10 @@ export declare namespace Catalog {
     type UnitGroupUnit as UnitGroupUnit,
     type UpdateUnitGroupRequest as UpdateUnitGroupRequest,
     type UnitGroupDeleteResponse as UnitGroupDeleteResponse,
-    type UnitGroupCreateParams as UnitGroupCreateParams,
+    type UnitGroupListParams as UnitGroupListParams,
     type UnitGroupRetrieveParams as UnitGroupRetrieveParams,
+    type UnitGroupCreateParams as UnitGroupCreateParams,
     type UnitGroupUpdateParams as UnitGroupUpdateParams,
-    type UnitGroupListParams as UnitGroupListParams,
   };
 
   export {
@@ -188,10 +188,10 @@ export declare namespace Catalog {
     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 {
@@ -202,10 +202,10 @@ export declare namespace Catalog {
     type ListItem as ListItem,
     type Quantity as Quantity,
     type Rate as Rate,
-    type ItemRetrieveParams as ItemRetrieveParams,
     type ItemListParams as ItemListParams,
-    type ItemChangeCategoryParams as ItemChangeCategoryParams,
+    type ItemRetrieveParams as ItemRetrieveParams,
     type ItemRetrieveInventoryParams as ItemRetrieveInventoryParams,
+    type ItemChangeCategoryParams as ItemChangeCategoryParams,
   };
 
   export {
@@ -215,10 +215,10 @@ export declare namespace Catalog {
     type UpdateItemCategoryRequest as UpdateItemCategoryRequest,
     type ItemCategoryDeleteResponse as ItemCategoryDeleteResponse,
     type ItemCategoryChangeUnitGroupResponse as ItemCategoryChangeUnitGroupResponse,
-    type ItemCategoryCreateParams as ItemCategoryCreateParams,
+    type ItemCategoryListParams as ItemCategoryListParams,
     type ItemCategoryRetrieveParams as ItemCategoryRetrieveParams,
+    type ItemCategoryCreateParams as ItemCategoryCreateParams,
     type ItemCategoryUpdateParams as ItemCategoryUpdateParams,
-    type ItemCategoryListParams as ItemCategoryListParams,
     type ItemCategoryChangeUnitGroupParams as ItemCategoryChangeUnitGroupParams,
   };
 
@@ -230,10 +230,10 @@ export declare namespace Catalog {
     type QuantityInputRequest as QuantityInputRequest,
     type RateInput as RateInput,
     type UpdateMaterialRequest as UpdateMaterialRequest,
-    type MaterialCreateParams as MaterialCreateParams,
+    type MaterialListParams as MaterialListParams,
     type MaterialRetrieveParams as MaterialRetrieveParams,
+    type MaterialCreateParams as MaterialCreateParams,
     type MaterialUpdateParams as MaterialUpdateParams,
-    type MaterialListParams as MaterialListParams,
   };
 
   export {
@@ -242,10 +242,10 @@ export declare namespace Catalog {
     type ListPart as ListPart,
     type Part as Part,
     type UpdatePartRequest as UpdatePartRequest,
-    type PartCreateParams as PartCreateParams,
+    type PartListParams as PartListParams,
     type PartRetrieveParams as PartRetrieveParams,
+    type PartCreateParams as PartCreateParams,
     type PartUpdateParams as PartUpdateParams,
-    type PartListParams as PartListParams,
   };
 
   export {
@@ -255,10 +255,10 @@ export declare namespace Catalog {
     type ProductLine as ProductLine,
     type UpdateProductLineRequest as UpdateProductLineRequest,
     type ProductLineDeleteResponse as ProductLineDeleteResponse,
-    type ProductLineCreateParams as ProductLineCreateParams,
+    type ProductLineListParams as ProductLineListParams,
     type ProductLineRetrieveParams as ProductLineRetrieveParams,
+    type ProductLineCreateParams as ProductLineCreateParams,
     type ProductLineUpdateParams as ProductLineUpdateParams,
-    type ProductLineListParams as ProductLineListParams,
   };
 
   export {
@@ -267,10 +267,10 @@ export declare namespace Catalog {
     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,
   };

package/src/resources/catalog/index.ts

@@ -8,10 +8,10 @@ export {
   type UpdateItemCategoryRequest,
   type ItemCategoryDeleteResponse,
   type ItemCategoryChangeUnitGroupResponse,
-  type ItemCategoryCreateParams,
+  type ItemCategoryListParams,
   type ItemCategoryRetrieveParams,
+  type ItemCategoryCreateParams,
   type ItemCategoryUpdateParams,
-  type ItemCategoryListParams,
   type ItemCategoryChangeUnitGroupParams,
 } from './item-categories/index';
 export {
@@ -22,10 +22,10 @@ export {
   type ListItem,
   type Quantity,
   type Rate,
-  type ItemRetrieveParams,
   type ItemListParams,
-  type ItemChangeCategoryParams,
+  type ItemRetrieveParams,
   type ItemRetrieveInventoryParams,
+  type ItemChangeCategoryParams,
 } from './items/index';
 export {
   Materials,
@@ -35,10 +35,10 @@ export {
   type QuantityInputRequest,
   type RateInput,
   type UpdateMaterialRequest,
-  type MaterialCreateParams,
+  type MaterialListParams,
   type MaterialRetrieveParams,
+  type MaterialCreateParams,
   type MaterialUpdateParams,
-  type MaterialListParams,
 } from './materials';
 export {
   Parts,
@@ -46,10 +46,10 @@ export {
   type ListPart,
   type Part,
   type UpdatePartRequest,
-  type PartCreateParams,
+  type PartListParams,
   type PartRetrieveParams,
+  type PartCreateParams,
   type PartUpdateParams,
-  type PartListParams,
 } from './parts';
 export {
   ProductLines,
@@ -58,10 +58,10 @@ export {
   type ProductLine,
   type UpdateProductLineRequest,
   type ProductLineDeleteResponse,
-  type ProductLineCreateParams,
+  type ProductLineListParams,
   type ProductLineRetrieveParams,
+  type ProductLineCreateParams,
   type ProductLineUpdateParams,
-  type ProductLineListParams,
 } from './product-lines';
 export {
   Products,
@@ -69,10 +69,10 @@ export {
   type ListProduct,
   type Product,
   type UpdateProductRequest,
-  type ProductCreateParams,
+  type ProductListParams,
   type ProductRetrieveParams,
+  type ProductCreateParams,
   type ProductUpdateParams,
-  type ProductListParams,
   type ProductDeleteParams,
   type ProductChangeProductLineParams,
 } from './products';
@@ -85,10 +85,10 @@ export {
   type Property,
   type UpdatePropertyRequest,
   type PropertyDeleteResponse,
-  type PropertyCreateParams,
+  type PropertyListParams,
   type PropertyRetrieveParams,
+  type PropertyCreateParams,
   type PropertyUpdateParams,
-  type PropertyListParams,
 } from './properties/index';
 export {
   UnitGroups,
@@ -100,10 +100,10 @@ export {
   type UnitGroupUnit,
   type UpdateUnitGroupRequest,
   type UnitGroupDeleteResponse,
-  type UnitGroupCreateParams,
+  type UnitGroupListParams,
   type UnitGroupRetrieveParams,
+  type UnitGroupCreateParams,
   type UnitGroupUpdateParams,
-  type UnitGroupListParams,
 } from './unit-groups/index';
 export {
   Units,
@@ -112,8 +112,8 @@ export {
   type Unit,
   type UpdateUnitRequest,
   type UnitDeleteResponse,
-  type UnitCreateParams,
+  type UnitListParams,
   type UnitRetrieveParams,
+  type UnitCreateParams,
   type UnitUpdateParams,
-  type UnitListParams,
 } from './units';