@cadenya/cadenya 0.134.0 → 1.0.0

package/src/resources/api-keys.ts

@@ -1,367 +1,308 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// Generated by redwood. Do not edit by hand.
 
-import { APIResource } from '../core/resource';
-import * as AccountAPI from './account';
-import * as Shared from './shared';
-import { APIPromise } from '../core/api-promise';
-import { CursorPagination, type CursorPaginationParams, PagePromise } from '../core/pagination';
-import { buildHeaders } from '../internal/headers';
-import { RequestOptions } from '../internal/request-options';
-import { path } from '../internal/utils/path';
+import { HttpClient, RequestOptions, APIPromise, pathSegment, snapshotParams } from '../core/http.js';
+import { Page } from '../core/pagination.js';
+import type { APIKey, APIKeySpecParam, CreateAccountResourceMetadata, ListAPIKeysResponse, UpdateAccountResourceMetadata } from '../types.js';
+import { wireAPIKeySpec } from '../types.js';
 
-/**
- * Issue, rotate, disable, and revoke a workspace's API keys. Every key
- *  belongs to exactly one workspace; the system-managed global account key is
- *  managed via GlobalAPIKeyService instead.
- */
-export class APIKeys extends APIResource {
+export interface ApiKeyListParams {
   /**
-   * Creates a new API key in the workspace.
+   * The workspace whose API keys will be listed (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  create(params: APIKeyCreateParams, options?: RequestOptions): APIPromise<APIKey> {
-    const { workspaceId = this._client.workspaceID, ...body } = params;
-    return this._client.post(path`/v1/workspaces/${workspaceId}/api_keys`, { body, ...options });
-  }
-
+  workspaceId?: string;
   /**
-   * Retrieves an API key by ID.
+   * Maximum number of results to return.
    */
-  retrieve(
-    id: string,
-    params: APIKeyRetrieveParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<APIKey> {
-    const { workspaceId = this._client.workspaceID } = params ?? {};
-    return this._client.get(path`/v1/workspaces/${workspaceId}/api_keys/${id}`, options);
-  }
-
+  limit?: number;
   /**
-   * Updates an API key.
+   * Pagination cursor from previous response.
    */
-  update(id: string, params: APIKeyUpdateParams, options?: RequestOptions): APIPromise<APIKey> {
-    const { workspaceId = this._client.workspaceID, ...body } = params;
-    return this._client.patch(path`/v1/workspaces/${workspaceId}/api_keys/${id}`, { body, ...options });
-  }
-
+  cursor?: string;
   /**
-   * Lists the workspace's API keys.
+   * Filter by ID prefix.
    */
-  list(
-    params: APIKeyListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<APIKeysCursorPagination, APIKey> {
-    const { workspaceId = this._client.workspaceID, ...query } = params ?? {};
-    return this._client.getAPIList(path`/v1/workspaces/${workspaceId}/api_keys`, CursorPagination<APIKey>, {
-      query,
-      ...options,
-    });
-  }
-
+  prefix?: string;
   /**
-   * Deletes an API key.
+   * Free-form search query.
    */
-  delete(
-    id: string,
-    params: APIKeyDeleteParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<void> {
-    const { workspaceId = this._client.workspaceID } = params ?? {};
-    return this._client.delete(path`/v1/workspaces/${workspaceId}/api_keys/${id}`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
-  }
-
+  query?: string;
   /**
-   * Disables an API key. While disabled, presenting the key's token fails
-   * authentication on every endpoint; the key is retained. Idempotent.
+   * Filters by metadata labels. Comma-separated key=value pairs,
+   *  e.g. "env=prod,team=ai". A resource matches only if every pair
+   *  matches exactly (AND semantics).
    */
-  disable(id: string, params: APIKeyDisableParams, options?: RequestOptions): APIPromise<APIKey> {
-    const { workspaceId = this._client.workspaceID, ...body } = params;
-    return this._client.post(path`/v1/workspaces/${workspaceId}/api_keys/${id}:disable`, {
-      body,
-      ...options,
-    });
-  }
-
+  labels?: string;
   /**
-   * Re-enables a disabled API key so its token authenticates again. Idempotent.
+   * Sort order for results (asc or desc by creation time).
    */
-  enable(id: string, params: APIKeyEnableParams, options?: RequestOptions): APIPromise<APIKey> {
-    const { workspaceId = this._client.workspaceID, ...body } = params;
-    return this._client.post(path`/v1/workspaces/${workspaceId}/api_keys/${id}:enable`, { body, ...options });
-  }
-
+  sortOrder?: string;
   /**
-   * Rotates an API key and returns a new token. All previous tokens for this key are
-   * invalidated.
+   * When true, included info fields are populated. Requests with this
+   *  flag count more against your rate limit.
    */
-  rotate(id: string, params: APIKeyRotateParams, options?: RequestOptions): APIPromise<APIKey> {
-    const { workspaceId = this._client.workspaceID, ...body } = params;
-    return this._client.post(path`/v1/workspaces/${workspaceId}/api_keys/${id}:rotate`, { body, ...options });
-  }
+  includeInfo?: boolean;
 }
 
-export type APIKeysCursorPagination = CursorPagination<APIKey>;
-
-/**
- * An API key. Every key belongs to exactly one workspace and is managed via the
- * workspace-scoped API key routes. The only exception is the system-managed global
- * account key, which spans all workspaces and is managed via the account
- * global_api_key routes.
- */
-export interface APIKey {
-  /**
-   * AccountResourceMetadata is used to represent a resource that is associated to an
-   * account but not to a workspace.
-   */
-  metadata: Shared.AccountResourceMetadata;
-
+export interface ApiKeyCreateParams {
+  metadata: CreateAccountResourceMetadata;
+  spec: APIKeySpecParam;
   /**
-   * Configuration for an API key.
+   * The workspace this API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  spec: APIKeySpec;
-
-  /**
-   * The current lifecycle state of the API key. Output only. Keys are created
-   * STATE_ENABLED; use the :disable and :enable actions to transition between
-   * states.
-   */
-  state: 'STATE_UNSPECIFIED' | 'STATE_ENABLED' | 'STATE_DISABLED';
-
-  info?: APIKeyInfo;
+  workspaceId?: string;
 }
 
-export interface APIKeyInfo {
+export interface ApiKeyRetrieveParams {
   /**
-   * A profile identifies a user or non-human principal (such as an API key) at the
-   * account level. Profiles are account-scoped and can be granted access to multiple
-   * workspaces.
+   * The workspace the API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  createdBy?: AccountAPI.Profile;
+  workspaceId?: string;
 }
 
-/**
- * Configuration for an API key.
- */
-export interface APIKeySpec {
-  /**
-   * The bearer token used to authenticate as this API key. Returned only on creation
-   * and rotation; subsequent reads omit this field.
-   */
-  token?: string;
-
-  /**
-   * Free-form description of what this API key is used for.
-   */
-  description?: string;
-
-  /**
-   * Scopes granted to this key. Each entry is a colon-separated resource:verb string
-   * (e.g. "objectives:manage").
-   *
-   * Resources: agents, objectives, tools, memory, api_keys, workspaces, widgets,
-   * widget_sessions, secrets, account. Verbs: read and manage, where manage implies
-   * read — a stored scope set is normalized to drop "x:read" when "x:manage" is
-   * present. The secrets and account resources support only manage. "\*" is an
-   * explicit full-access grant.
-   *
-   * Scopes are deny-by-default: a key with an empty list can call only scope-free
-   * endpoints. Full access is always an explicit "\*" grant.
-   */
-  permissions?: Array<string>;
-
+export interface ApiKeyDeleteParams {
   /**
-   * True when this key is managed by the system (i.e. the auto-provisioned global
-   * account key). System keys cannot be deleted but can be rotated.
+   * The workspace the API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  system?: boolean;
+  workspaceId?: string;
 }
 
-export interface APIKeyCreateParams {
+export interface ApiKeyUpdateParams {
   /**
-   * Path param: The workspace this API key belongs to (path).
+   * The workspace the API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   workspaceId?: string;
-
-  /**
-   * Body param: CreateAccountResourceMetadata contains the user-provided fields for
-   * creating an account-scoped resource. Read-only fields (id, account_id,
-   * profile_id) are excluded since they are set by the server.
-   */
-  metadata: APIKeyCreateParams.Metadata;
-
+  metadata?: UpdateAccountResourceMetadata;
+  spec?: APIKeySpecParam;
   /**
-   * Body param: Configuration for an API key.
+   * Fields to update.
    */
-  spec: APIKeySpec;
+  updateMask?: string;
 }
 
-export namespace APIKeyCreateParams {
+export interface ApiKeyDisableParams {
   /**
-   * CreateAccountResourceMetadata contains the user-provided fields for creating an
-   * account-scoped resource. Read-only fields (id, account_id, profile_id) are
-   * excluded since they are set by the server.
+   * The workspace the API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
-  export interface Metadata {
-    /**
-     * Human-readable name for the resource (e.g., "Production API Key", "Staging
-     * Workspace")
-     */
-    name: string;
-
-    /**
-     * External ID for the resource (e.g., a workflow ID from an external system)
-     */
-    externalId?: string;
-
-    /**
-     * Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric
-     * characters with "-", "\_", or "." allowed between; keys follow the same shape
-     * and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/")
-     * of at most 253 characters. Examples: {"environment": "production", "team":
-     * "platform", "version": "v2"}
-     */
-    labels?: { [key: string]: string };
-  }
+  workspaceId?: string;
 }
 
-export interface APIKeyRetrieveParams {
+export interface ApiKeyEnableParams {
   /**
    * The workspace the API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   workspaceId?: string;
 }
 
-export interface APIKeyUpdateParams {
+export interface ApiKeyRotateParams {
   /**
-   * Path param: The workspace the API key belongs to (path).
+   * The workspace the API key belongs to (path).
+   * 
+   * Defaults to the client-level `workspaceId` option or the CADENYA_WORKSPACE_ID environment variable.
    */
   workspaceId?: string;
+}
 
-  /**
-   * Body param: UpdateAccountResourceMetadata contains the user-provided fields for
-   * updating an account-scoped resource. Read-only fields (id, account_id,
-   * profile_id) are excluded since they are set by the server.
-   */
-  metadata?: APIKeyUpdateParams.Metadata;
-
-  /**
-   * Body param: Configuration for an API key.
-   */
-  spec?: APIKeySpec;
+export class ApiKeys {
+  constructor(private readonly _client: HttpClient) {}
 
   /**
-   * Body param: Fields to update.
+   * Get the global API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.retrieveGlobal();
+   * ```
    */
-  updateMask?: string;
-}
+  retrieveGlobal(options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      return { method: 'GET', path: `/v1/account/global_api_key` };
+    }, options);
+  }
 
-export namespace APIKeyUpdateParams {
   /**
-   * UpdateAccountResourceMetadata contains the user-provided fields for updating an
-   * account-scoped resource. Read-only fields (id, account_id, profile_id) are
-   * excluded since they are set by the server.
+   * Disable the global API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.disableGlobal();
+   * ```
    */
-  export interface Metadata {
-    /**
-     * Human-readable name for the resource (e.g., "Production API Key", "Staging
-     * Workspace")
-     */
-    name: string;
-
-    /**
-     * External ID for the resource (e.g., a workflow ID from an external system)
-     */
-    externalId?: string;
-
-    /**
-     * Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric
-     * characters with "-", "\_", or "." allowed between; keys follow the same shape
-     * and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/")
-     * of at most 253 characters. Examples: {"environment": "production", "team":
-     * "platform", "version": "v2"}
-     */
-    labels?: { [key: string]: string };
+  disableGlobal(options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      return { method: 'POST', path: `/v1/account/global_api_key:disable` };
+    }, options);
   }
-}
 
-export interface APIKeyListParams extends CursorPaginationParams {
   /**
-   * Path param: The workspace whose API keys will be listed (path).
+   * Enable the global API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.enableGlobal();
+   * ```
    */
-  workspaceId?: string;
+  enableGlobal(options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      return { method: 'POST', path: `/v1/account/global_api_key:enable` };
+    }, options);
+  }
 
   /**
-   * Query param: When true, included info fields are populated. Requests with this
-   * flag count more against your rate limit.
+   * Rotate the global API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.rotateGlobal();
+   * ```
    */
-  includeInfo?: boolean;
+  rotateGlobal(options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      return { method: 'POST', path: `/v1/account/global_api_key:rotate` };
+    }, options);
+  }
 
   /**
-   * Query param: Filters by metadata labels. Comma-separated key=value pairs, e.g.
-   * "env=prod,team=ai". A resource matches only if every pair matches exactly (AND
-   * semantics).
-   */
-  labels?: string;
+   * List API keys
+   * 
+   * @example
+   * ```ts
+   * const page = await client.apiKeys.list();
+   * for await (const item of page) {
+   *   // auto-fetches every page
+   * }
+   * ```
+   */
+  async list(params?: ApiKeyListParams, options?: RequestOptions): Promise<Page<APIKey>> {
+    const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+    if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+    const _base = snapshotParams(params);
+    const response = await this._client.request<ListAPIKeysResponse>({ method: 'GET', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys`, query: { limit: params?.limit, cursor: params?.cursor, prefix: params?.prefix, query: params?.query, labels: params?.labels, sortOrder: params?.sortOrder, includeInfo: params?.includeInfo } }, options);
+    return new Page(response.items ?? [], response.pagination?.nextCursor, (cursor) => this.list({ ..._base, cursor: cursor }, options));
+  }
 
   /**
-   * Query param: Filter by ID prefix.
+   * Create a new API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.create({ metadata: { name: 'sample' }, spec: {  } });
+   * ```
    */
-  prefix?: string;
+  create(params: ApiKeyCreateParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      const workspaceId = String(params.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys`, body: { metadata: params.metadata, spec: wireAPIKeySpec(params.spec) } };
+    }, options);
+  }
 
   /**
-   * Query param: Free-form search query.
+   * Get an API key by ID
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.retrieve('_123');
+   * ```
    */
-  query?: string;
+  retrieve(id: string, params?: ApiKeyRetrieveParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'GET', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys/${pathSegment('id', id)}` };
+    }, options);
+  }
 
   /**
-   * Query param: Sort order for results (asc or desc by creation time).
+   * Delete an API key
+   * 
+   * @example
+   * ```ts
+   * await client.apiKeys.delete('_123');
+   * ```
    */
-  sortOrder?: string;
-}
+  delete(id: string, params?: ApiKeyDeleteParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.requestAPI<void>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'DELETE', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys/${pathSegment('id', id)}`, void: true };
+    }, options);
+  }
 
-export interface APIKeyDeleteParams {
   /**
-   * The workspace the API key belongs to (path).
+   * Update an API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.update('_123');
+   * ```
    */
-  workspaceId?: string;
-}
+  update(id: string, params?: ApiKeyUpdateParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'PATCH', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys/${pathSegment('id', id)}`, body: { metadata: params?.metadata, spec: wireAPIKeySpec(params?.spec), updateMask: params?.updateMask } };
+    }, options);
+  }
 
-export interface APIKeyDisableParams {
   /**
-   * The workspace the API key belongs to (path).
+   * Disable an API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.disable('_123');
+   * ```
    */
-  workspaceId?: string;
-}
+  disable(id: string, params?: ApiKeyDisableParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys/${pathSegment('id', id)}:disable` };
+    }, options);
+  }
 
-export interface APIKeyEnableParams {
   /**
-   * The workspace the API key belongs to (path).
+   * Enable an API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.enable('_123');
+   * ```
    */
-  workspaceId?: string;
-}
+  enable(id: string, params?: ApiKeyEnableParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys/${pathSegment('id', id)}:enable` };
+    }, options);
+  }
 
-export interface APIKeyRotateParams {
   /**
-   * The workspace the API key belongs to (path).
+   * Rotate an API key
+   * 
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.rotate('_123');
+   * ```
    */
-  workspaceId?: string;
-}
-
-export declare namespace APIKeys {
-  export {
-    type APIKey as APIKey,
-    type APIKeyInfo as APIKeyInfo,
-    type APIKeySpec as APIKeySpec,
-    type APIKeysCursorPagination as APIKeysCursorPagination,
-    type APIKeyCreateParams as APIKeyCreateParams,
-    type APIKeyRetrieveParams as APIKeyRetrieveParams,
-    type APIKeyUpdateParams as APIKeyUpdateParams,
-    type APIKeyListParams as APIKeyListParams,
-    type APIKeyDeleteParams as APIKeyDeleteParams,
-    type APIKeyDisableParams as APIKeyDisableParams,
-    type APIKeyEnableParams as APIKeyEnableParams,
-    type APIKeyRotateParams as APIKeyRotateParams,
-  };
+  rotate(id: string, params?: ApiKeyRotateParams, options?: RequestOptions): APIPromise<APIKey> {
+    return this._client.requestAPI<APIKey>(() => {
+      const workspaceId = String(params?.workspaceId ?? this._client.defaults['workspaceId'] ?? '').trim() || undefined;
+      if (workspaceId === undefined) throw new Error("Missing 'workspaceId': pass it in params, set it on the client, or set the CADENYA_WORKSPACE_ID environment variable.");
+      return { method: 'POST', path: `/v1/workspaces/${pathSegment('workspaceId', workspaceId)}/api_keys/${pathSegment('id', id)}:rotate` };
+    }, options);
+  }
 }