@augno/sdk 0.1.9 → 0.7.0

package/src/resources/core/request-logs.ts

@@ -11,36 +11,36 @@ import { path } from '../../internal/utils/path';
  */
 export class RequestLogs extends APIResource {
   /**
-   * Returns a request log by ID.
+   * Returns a paginated list of request logs for the current account.
    *
    * @example
    * ```ts
-   * const requestLog = await client.core.requestLogs.retrieve(
-   *   'rq_01304bffe90e8cce9690cbefd4',
-   * );
+   * const listRequestLog = await client.core.requestLogs.list();
    * ```
    */
-  retrieve(
-    id: string,
-    query: RequestLogRetrieveParams | null | undefined = {},
+  list(
+    query: RequestLogListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<RequestLog> {
-    return this._client.get(path`/v1/core/request-logs/${id}`, { query, ...options });
+  ): APIPromise<ListRequestLog> {
+    return this._client.get('/v1/core/request-logs', { query, ...options });
   }
 
   /**
-   * Returns a paginated list of request logs.
+   * Returns a request log by ID.
    *
    * @example
    * ```ts
-   * const listRequestLog = await client.core.requestLogs.list();
+   * const requestLog = await client.core.requestLogs.retrieve(
+   *   'rq_01304bffe90e8cce9690cbefd4',
+   * );
    * ```
    */
-  list(
-    query: RequestLogListParams | null | undefined = {},
+  retrieve(
+    id: string,
+    query: RequestLogRetrieveParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ListRequestLog> {
-    return this._client.get('/v1/core/request-logs', { query, ...options });
+  ): APIPromise<RequestLog> {
+    return this._client.get(path`/v1/core/request-logs/${id}`, { query, ...options });
   }
 }
 
@@ -54,13 +54,17 @@ export interface Actor {
   id: string;
 
   /**
-   * Human-readable handle (`email` for users, `redacted_value` for API keys, `slug`
-   * for agents).
+   * Human-readable handle identifying the actor.
+   *
+   * - For `user` actors: the user's email address.
+   * - For `api_key` actors: the redacted key value.
+   *
+   * Agent actors carry no handle.
    */
   handle: string | null;
 
   /**
-   * Display name.
+   * The actor's display name.
    */
   name: string | null;
 
@@ -70,12 +74,17 @@ export interface Actor {
   object: 'actor';
 
   /**
-   * Role resource.
+   * A named set of permissions that can be assigned to users to control what they
+   * can access.
    */
   role: APIKeysAPI.Role | null;
 
   /**
    * Actor type.
+   *
+   * - `user`: a human user account.
+   * - `api_key`: a programmatic caller authenticating with an API key.
+   * - `agent`: an automated agent acting on the account's behalf.
    */
   type: 'user' | 'api_key' | 'agent';
 }
@@ -101,7 +110,7 @@ export interface ListRequestLog {
 }
 
 /**
- * RequestLog is an API request log entry.
+ * A log of a single API request, capturing its route, outcome, latency, and actor.
  */
 export interface RequestLog {
   /**
@@ -110,7 +119,7 @@ export interface RequestLog {
   id: string;
 
   /**
-   * Account with optional branding and portal sub-resources.
+   * A customer account, including its branding and customer portal sub-resources.
    */
   account: APIKeysAPI.Account | null;
 
@@ -135,17 +144,23 @@ export interface RequestLog {
   created_at: string;
 
   /**
-   * API error code.
+   * Machine-readable API error code.
+   *
+   * Populated only for failed requests.
    */
   error_code: string | null;
 
   /**
-   * Error message.
+   * Human-readable error message.
+   *
+   * Populated only for failed requests.
    */
   error_message: string | null;
 
   /**
-   * Request host. Usually `api.augno.com`.
+   * Request host.
+   *
+   * Usually `api.augno.com`.
    */
   host: string;
 
@@ -165,8 +180,12 @@ export interface RequestLog {
   method: string;
 
   /**
-   * _Normalized_ route template. For example `PATCH /v1/sales/customers/{id}` is the
-   * normalized route for a request route `PUT /v1/sales/customers/ac_...`.
+   * The route template the request matched, with path parameters left as
+   * placeholders.
+   *
+   * For example `/v1/sales/customers/{id}` is the normalized route for the request
+   * path `/v1/sales/customers/ac_...`. Falls back to the raw path when the request
+   * did not match a registered route.
    */
   normalized_route: string;
 
@@ -209,7 +228,7 @@ export interface RequestLog {
   response_body: unknown | null;
 
   /**
-   * HTTP status code.
+   * HTTP response status code (e.g. `200`, `404`).
    */
   status_code: number;
 
@@ -219,40 +238,23 @@ export interface RequestLog {
   user_agent: string | null;
 }
 
-export interface RequestLogRetrieveParams {
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<
-    | 'account'
-    | 'actor'
-    | 'actor.role'
-    | 'actor.role.permissions'
-    | 'query_params'
-    | 'request_body'
-    | 'response_body'
-  >;
-}
-
 export interface RequestLogListParams {
   /**
-   * Filter by the _acting_ account: the account the actor belongs to, not the
-   * account targeted by the request.
+   * Filter by the _acting_ account: the account the actor belongs to (the log's
+   * `account.id`).
    *
-   * This is usually your own account, but differs when another account acts on yours
-   * — for example a customer using a customer-portal API key, whose acting account
-   * is the customer's account. The request's target account is always your own
-   * account (the only account you are authorized to view request logs for), so this
-   * filter narrows by _who acted_, not by which account was acted upon.
+   * Results are always scoped to logs where your account is either the acting
+   * account or the target account; this narrows that set to specific acting
+   * accounts. For example, pass a customer's account ID to see only requests that
+   * customer's actors made against your account.
    */
-  account_ids?: Array<string>;
+  actor_account_ids?: Array<string>;
 
   /**
    * Filter by the actor identifier.
    *
-   * This is the `user.id` when `identity_type`=`user` and an `api_key.id` when
-   * `identity_type`=`api_key`.
+   * Matches the log's `actor.id`: a user ID for `user` actors or an API key ID for
+   * `api_key` actors.
    */
   actor_ids?: Array<string>;
 
@@ -262,7 +264,11 @@ export interface RequestLogListParams {
   actor_types?: Array<'user' | 'api_key' | 'agent'>;
 
   /**
-   * 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;
 
@@ -310,7 +316,9 @@ export interface RequestLogListParams {
   >;
 
   /**
-   * Filter by the request host. Typically, `api.augno.com`.
+   * Filter by the request host.
+   *
+   * Typically `api.augno.com`.
    */
   hosts?: Array<string>;
 
@@ -326,7 +334,7 @@ export interface RequestLogListParams {
   include?: Array<'account' | 'actor' | 'actor.role'>;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
+   * Maximum number of results to return in a single page.
    */
   limit?: number;
 
@@ -336,20 +344,23 @@ export interface RequestLogListParams {
   methods?: Array<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'>;
 
   /**
-   * Filter by the minimum latency in microseconds.
+   * Restricts results to requests that took at least this many microseconds.
    */
   min_latency_us?: number;
 
   /**
    * Filter by the _normalized_ route template.
    *
-   * For example `PATCH /v1/sales/customers/{id}` is the normalized route for a
-   * request route `PUT /v1/sales/customers/ac_...`.
+   * For example `/v1/sales/customers/{id}` matches every request to that route
+   * regardless of the specific customer ID. Parameter names inside `{}` are ignored
+   * when matching, so `{customer_id}` and `{id}` are equivalent.
    */
   normalized_routes?: Array<string>;
 
   /**
-   * 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;
 
@@ -359,9 +370,11 @@ export interface RequestLogListParams {
   start_date?: string;
 
   /**
-   * Filter by the HTTP status class: 1–5 for 1xx–5xx. Combined with `status_codes`
-   * using OR — e.g. status_codes=401 and status_code_classes=5 matches 401 and any
-   * 5xx.
+   * Filter by the HTTP status class, expressed as the leading digit: `1`–`5` for
+   * 1xx–5xx.
+   *
+   * Combined with `status_codes` using OR — e.g. `status_codes=401` and
+   * `status_code_classes=5` matches 401 responses and any 5xx response.
    */
   status_code_classes?: Array<number>;
 
@@ -369,6 +382,33 @@ export interface RequestLogListParams {
    * Filter by the HTTP status code.
    */
   status_codes?: Array<number>;
+
+  /**
+   * Filter by the _target_ account: the account the request acted upon (the log's
+   * target account).
+   *
+   * Results are always scoped to logs where your account is either the acting
+   * account or the target account; this narrows that set to specific target
+   * accounts. For example, pass a supplier's account ID to see only requests your
+   * account made against that supplier.
+   */
+  target_account_ids?: Array<string>;
+}
+
+export interface RequestLogRetrieveParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<
+    | 'account'
+    | 'actor'
+    | 'actor.role'
+    | 'actor.role.permissions'
+    | 'query_params'
+    | 'request_body'
+    | 'response_body'
+  >;
 }
 
 export declare namespace RequestLogs {
@@ -376,7 +416,7 @@ export declare namespace RequestLogs {
     type Actor as Actor,
     type ListRequestLog as ListRequestLog,
     type RequestLog as RequestLog,
-    type RequestLogRetrieveParams as RequestLogRetrieveParams,
     type RequestLogListParams as RequestLogListParams,
+    type RequestLogRetrieveParams as RequestLogRetrieveParams,
   };
 }

package/src/resources/core/sandboxes.ts

@@ -11,18 +11,15 @@ import { path } from '../../internal/utils/path';
  */
 export class Sandboxes extends APIResource {
   /**
-   * Creates a sandbox account.
+   * Returns a paginated list of sandboxes.
    *
    * @example
    * ```ts
-   * const sandbox = await client.core.sandboxes.create({
-   *   name: 'Integration Testing',
-   * });
+   * const listSandbox = await client.core.sandboxes.list();
    * ```
    */
-  create(params: SandboxCreateParams, options?: RequestOptions): APIPromise<Sandbox> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/core/sandboxes', { query: { include }, body, ...options });
+  list(query: SandboxListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListSandbox> {
+    return this._client.get('/v1/core/sandboxes', { query, ...options });
   }
 
   /**
@@ -44,20 +41,30 @@ export class Sandboxes extends APIResource {
   }
 
   /**
-   * Returns a paginated list of sandboxes.
+   * Creates a sandbox account owned by your production account.
+   *
+   * When `mode` is `seeded`, sample data is populated asynchronously and may not be
+   * available immediately after the sandbox is created. Sandboxes cannot be created
+   * while acting in a sandbox.
    *
    * @example
    * ```ts
-   * const listSandbox = await client.core.sandboxes.list();
+   * const sandbox = await client.core.sandboxes.create({
+   *   name: 'Integration Testing',
+   *   mode: 'blank',
+   * });
    * ```
    */
-  list(query: SandboxListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListSandbox> {
-    return this._client.get('/v1/core/sandboxes', { query, ...options });
+  create(params: SandboxCreateParams, options?: RequestOptions): APIPromise<Sandbox> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/core/sandboxes', { query: { include }, body, ...options });
   }
 
   /**
-   * Deletes a sandbox account. At least one sandbox must remain per production
-   * account.
+   * Deletes a sandbox account.
+   *
+   * The sandbox's data is purged asynchronously, so it may persist briefly after
+   * this call returns.
    *
    * @example
    * ```ts
@@ -81,7 +88,11 @@ export interface CreateSandboxRequest {
   name: string;
 
   /**
-   * Controls whether the sandbox is blank or seeded with sample data.
+   * Controls how the sandbox is initialized.
+   *
+   * - `blank`: starts empty, with no pre-populated data.
+   * - `seeded`: starts with sample data, populated asynchronously after the sandbox
+   *   is created.
    */
   mode?: 'blank' | 'seeded';
 }
@@ -131,7 +142,7 @@ export interface Sandbox {
   object: 'sandbox';
 
   /**
-   * Account with optional branding and portal sub-resources.
+   * A customer account, including its branding and customer portal sub-resources.
    */
   owner_account: APIKeysAPI.Account | null;
 
@@ -143,22 +154,33 @@ export interface Sandbox {
 
 export interface SandboxDeleteResponse {}
 
-export interface SandboxCreateParams {
+export interface SandboxListParams {
   /**
-   * Body param: Display 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<'owner_account'>;
 
   /**
-   * Body param: Controls whether the sandbox is blank or seeded with sample data.
+   * Maximum number of results to return in a single page.
    */
-  mode?: 'blank' | 'seeded';
+  limit?: number;
+
+  /**
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
+   */
+  q?: string;
 }
 
 export interface SandboxRetrieveParams {
@@ -169,27 +191,26 @@ export interface SandboxRetrieveParams {
   include?: Array<'owner_account'>;
 }
 
-export interface SandboxListParams {
+export interface SandboxCreateParams {
   /**
-   * Cursor token used to retrieve the next or previous page of results.
+   * Body param: Display name.
    */
-  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<'owner_account'>;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
-   */
-  limit?: number;
-
-  /**
-   * Search query used to filter results.
+   * Body param: Controls how the sandbox is initialized.
+   *
+   * - `blank`: starts empty, with no pre-populated data.
+   * - `seeded`: starts with sample data, populated asynchronously after the sandbox
+   *   is created.
    */
-  q?: string;
+  mode?: 'blank' | 'seeded';
 }
 
 export declare namespace Sandboxes {
@@ -198,8 +219,8 @@ export declare namespace Sandboxes {
     type ListSandbox as ListSandbox,
     type Sandbox as Sandbox,
     type SandboxDeleteResponse as SandboxDeleteResponse,
-    type SandboxCreateParams as SandboxCreateParams,
-    type SandboxRetrieveParams as SandboxRetrieveParams,
     type SandboxListParams as SandboxListParams,
+    type SandboxRetrieveParams as SandboxRetrieveParams,
+    type SandboxCreateParams as SandboxCreateParams,
   };
 }