@augno/sdk 0.1.9 → 0.7.1

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

@@ -12,41 +12,46 @@ import { path } from '../../internal/utils/path';
  */
 export class EmailLogs extends APIResource {
   /**
-   * Returns an email log by ID.
+   * Returns a paginated list of email logs for the current account.
+   *
+   * This endpoint requires the permission: `email_logs:read`.
    *
    * @example
    * ```ts
-   * const emailLog = await client.core.emailLogs.retrieve(
-   *   'eml_017b80707ada92dddff8a2c3a0',
-   * );
+   * const listEmailLog = await client.core.emailLogs.list();
    * ```
    */
-  retrieve(
-    id: string,
-    query: EmailLogRetrieveParams | null | undefined = {},
+  list(
+    query: EmailLogListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<EmailLog> {
-    return this._client.get(path`/v1/core/email-logs/${id}`, { query, ...options });
+  ): APIPromise<ListEmailLog> {
+    return this._client.get('/v1/core/email-logs', { query, ...options });
   }
 
   /**
-   * Returns a paginated list of email logs for the current account.
+   * Returns an email log by ID.
+   *
+   * This endpoint requires the permission: `email_logs:read`.
    *
    * @example
    * ```ts
-   * const listEmailLog = await client.core.emailLogs.list();
+   * const emailLog = await client.core.emailLogs.retrieve(
+   *   'eml_017b80707ada92dddff8a2c3a0',
+   * );
    * ```
    */
-  list(
-    query: EmailLogListParams | null | undefined = {},
+  retrieve(
+    id: string,
+    query: EmailLogRetrieveParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<ListEmailLog> {
-    return this._client.get('/v1/core/email-logs', { query, ...options });
+  ): APIPromise<EmailLog> {
+    return this._client.get(path`/v1/core/email-logs/${id}`, { query, ...options });
   }
 }
 
 /**
- * Email log entry.
+ * A record of an email sent on the account's behalf, such as an invoice or a user
+ * invitation.
  */
 export interface EmailLog {
   /**
@@ -60,7 +65,7 @@ export interface EmailLog {
   created_at: string;
 
   /**
-   * Filename of any attachment.
+   * Filename of the attached document.
    */
   filename: string | null;
 
@@ -76,11 +81,15 @@ export interface EmailLog {
 
   /**
    * Email send status.
+   *
+   * - `pending`: the email is queued and has not been sent yet.
+   * - `sent`: the email has been handed off for delivery.
    */
   send_status: 'sent' | 'pending';
 
   /**
-   * Reference to an actor (user, API key, or agent).
+   * Reference to an actor — the user, API key, agent, or group identity associated
+   * with an action.
    */
   sent_by: RequestLogsAPI.Actor | null;
 
@@ -115,17 +124,13 @@ export interface ListEmailLog {
   page_info: APIKeysAPI.PageInfo;
 }
 
-export interface EmailLogRetrieveParams {
-  /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
-   */
-  include?: Array<'sent_by'>;
-}
-
 export interface EmailLogListParams {
   /**
-   * 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;
 
@@ -136,21 +141,31 @@ export interface EmailLogListParams {
   include?: Array<'sent_by'>;
 
   /**
-   * 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;
 }
 
+export interface EmailLogRetrieveParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'sent_by'>;
+}
+
 export declare namespace EmailLogs {
   export {
     type EmailLog as EmailLog,
     type ListEmailLog as ListEmailLog,
-    type EmailLogRetrieveParams as EmailLogRetrieveParams,
     type EmailLogListParams as EmailLogListParams,
+    type EmailLogRetrieveParams as EmailLogRetrieveParams,
   };
 }

package/src/resources/core/index.ts

@@ -13,24 +13,24 @@ export {
   type ListAuditEvent,
   type ListAuditFieldChange,
   type ListObjectType,
-  type AuditEventRetrieveParams,
   type AuditEventListParams,
+  type AuditEventRetrieveParams,
 } from './audit-events';
-export { Core } from './core';
+export { Core, type Entity, type ListEntity, type CoreRetrieveSearchParams } from './core';
 export {
   EmailLogs,
   type EmailLog,
   type ListEmailLog,
-  type EmailLogRetrieveParams,
   type EmailLogListParams,
+  type EmailLogRetrieveParams,
 } from './email-logs';
 export {
   RequestLogs,
   type Actor,
   type ListRequestLog,
   type RequestLog,
-  type RequestLogRetrieveParams,
   type RequestLogListParams,
+  type RequestLogRetrieveParams,
 } from './request-logs';
 export {
   Sandboxes,
@@ -38,7 +38,7 @@ export {
   type ListSandbox,
   type Sandbox,
   type SandboxDeleteResponse,
-  type SandboxCreateParams,
-  type SandboxRetrieveParams,
   type SandboxListParams,
+  type SandboxRetrieveParams,
+  type SandboxCreateParams,
 } from './sandboxes';

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

@@ -11,56 +11,72 @@ 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.
+   *
+   * This endpoint requires the permission: `request_logs:read`.
    *
    * @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.
+   *
+   * This endpoint requires the permission: `request_logs:read`.
    *
    * @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 });
   }
 }
 
 /**
- * Reference to an actor (user, API key, or agent).
+ * Reference to an actor — the user, API key, agent, or group identity associated
+ * with an action.
  */
 export interface Actor {
   /**
-   * Actor ID.
+   * Unique identifier of the actor.
    */
   id: string;
 
   /**
-   * Human-readable handle (`email` for users, `redacted_value` for API keys, `slug`
-   * for agents).
+   * URL of the actor's profile photo, if one is set.
+   *
+   * Only populated for `user` actors.
+   */
+  avatar_url: string | null;
+
+  /**
+   * Human-readable handle identifying the actor.
+   *
+   * - For `user` actors: the user's email address.
+   * - For `api_key` actors: the redacted key value.
+   *
+   * Other actor types carry no handle.
    */
   handle: string | null;
 
   /**
-   * Display name.
+   * The actor's display name.
    */
   name: string | null;
 
@@ -70,14 +86,21 @@ 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.
+   * - `group`: a shared group identity, such as a "Customer Service" persona, rather
+   *   than a single individual.
    */
-  type: 'user' | 'api_key' | 'agent';
+  type: 'user' | 'api_key' | 'agent' | 'group';
 }
 
 /**
@@ -101,7 +124,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,12 +133,13 @@ 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;
 
   /**
-   * Reference to an actor (user, API key, or agent).
+   * Reference to an actor — the user, API key, agent, or group identity associated
+   * with an action.
    */
   actor: Actor | null;
 
@@ -135,17 +159,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 +195,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;
 
@@ -181,7 +215,7 @@ export interface RequestLog {
   occurred_at: string;
 
   /**
-   * Non-normalized request path.
+   * The exact path the request was made to, including path parameter values.
    */
   path: string;
 
@@ -209,7 +243,7 @@ export interface RequestLog {
   response_body: unknown | null;
 
   /**
-   * HTTP status code.
+   * HTTP response status code (e.g. `200`, `404`).
    */
   status_code: number;
 
@@ -219,50 +253,37 @@ 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>;
 
   /**
    * Filter by the actor type.
    */
-  actor_types?: Array<'user' | 'api_key' | 'agent'>;
+  actor_types?: Array<'user' | 'api_key' | 'agent' | 'group'>;
 
   /**
-   * 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 +331,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 +349,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 +359,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 +385,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 +397,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 +431,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,
   };
 }