@augno/sdk 0.1.9 → 0.7.1

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

@@ -13,31 +13,11 @@ 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.
    *
+   * This endpoint requires the `admin` role type.
+   *
    * @example
    * ```ts
    * const apiKey = await client.auth.apiKeys.retrieve(
@@ -56,6 +36,8 @@ export class APIKeys extends APIResource {
   /**
    * Returns a paginated list of [API keys](https://docs.augno.com/api/api-keys).
    *
+   * This endpoint requires the `admin` role type.
+   *
    * @example
    * ```ts
    * const listAPIKey = await client.auth.apiKeys.list();
@@ -65,10 +47,38 @@ 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.
+   *
+   * This endpoint requires the `admin` role type.
+   *
+   * @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.
+   *
+   * This endpoint requires the `admin` role type.
    *
    * @example
    * ```ts
@@ -83,7 +93,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,17 +112,19 @@ 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;
 
   /**
-   * Display name.
+   * The account's display name.
    */
   name: string;
 
@@ -217,7 +229,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 +242,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 +262,7 @@ export interface Address {
   email: string | null;
 
   /**
-   * Geolocation sub-resource.
+   * The street-level location details of an address.
    */
   geolocation: Geolocation | null;
 
@@ -267,7 +282,11 @@ export interface Address {
   phone: string | null;
 
   /**
-   * Address type.
+   * How the address is used.
+   *
+   * - `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 +297,7 @@ export interface Address {
 }
 
 /**
- * API key resource.
+ * An API key used to authenticate requests to the Augno API.
  */
 export interface APIKey {
   /**
@@ -292,12 +311,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 +337,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 +374,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 +393,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 +412,7 @@ export interface CreatedAPIKey {
 }
 
 /**
- * Geolocation sub-resource.
+ * The street-level location details of an address.
  */
 export interface Geolocation {
   /**
@@ -443,7 +481,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 +491,12 @@ export interface Owner {
   object: 'owner';
 
   /**
-   * The owner type: "system" for platform defaults, "account" for account-owned
-   * resources.
+   * Where this 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 +516,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 +546,7 @@ export interface Role {
   created_at: string;
 
   /**
-   * Display name.
+   * Display name, unique within the account.
    */
   name: string;
 
@@ -514,16 +561,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 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.
+   * 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.
+   *
+   * - `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 +590,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 +600,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 +615,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 +683,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,
   };