@naturalpay/sdk 0.2.0 → 0.3.0

package/src/resources/api-keys.ts

@@ -0,0 +1,743 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * API key management
+ */
+export class APIKeys extends APIResource {
+  /**
+   * Create a new API key. The full secret is returned only once.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.create({ name: 'x' });
+   * ```
+   */
+  create(params: APIKeyCreateParams, options?: RequestOptions): APIPromise<APIKeyCreateResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...body } = params;
+    return this._client.post('/api-keys', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get API keys for the user's party.
+   *
+   * @example
+   * ```ts
+   * const apiKeys = await client.apiKeys.list();
+   * ```
+   */
+  list(
+    params: APIKeyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<APIKeyListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/api-keys', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get details of a specific API key.
+   *
+   * @example
+   * ```ts
+   * const apiKey = await client.apiKeys.get('keyId');
+   * ```
+   */
+  get(
+    keyID: string,
+    params: APIKeyGetParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<APIKeyGetResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.get(path`/api-keys/${keyID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Revoke an API key so it can no longer be used for authentication.
+   *
+   * @example
+   * ```ts
+   * const response = await client.apiKeys.revoke('keyId');
+   * ```
+   */
+  revoke(
+    keyID: string,
+    params: APIKeyRevokeParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<APIKeyRevokeResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.post(path`/api-keys/${keyID}/revoke`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface APIKeyCreateResponse {
+  data: APIKeyCreateResponse.Data;
+}
+
+export namespace APIKeyCreateResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Full API key secret (shown only once - store securely!)
+       */
+      apiKey: string;
+
+      /**
+       * Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The middle segment
+       * encodes the environment; the final segment is random.
+       */
+      apiKeyPrefix: string;
+
+      /**
+       * When this key was created
+       */
+      createdAt: string;
+
+      /**
+       * User who created this key (usr\_\*)
+       */
+      createdBy: string | null;
+
+      /**
+       * Environment
+       */
+      environment: 'sandbox' | 'prod';
+
+      /**
+       * When this key was last used
+       */
+      lastUsedAt: string | null;
+
+      /**
+       * Human-readable name
+       */
+      name: string;
+
+      /**
+       * When this key was revoked
+       */
+      revokedAt: string | null;
+
+      /**
+       * User who revoked this key (usr\_\*)
+       */
+      revokedBy: string | null;
+
+      /**
+       * Authorized scopes
+       */
+      scopes: Array<string>;
+
+      /**
+       * Status (ACTIVE or REVOKED)
+       */
+      status: 'ACTIVE' | 'REVOKED';
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the API key
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the API key
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface APIKeyListResponse {
+  data: Array<APIKeyListResponse.Data>;
+
+  meta: APIKeyListResponse.Meta;
+}
+
+export namespace APIKeyListResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The middle segment
+       * encodes the environment; the final segment is random.
+       */
+      apiKeyPrefix: string;
+
+      /**
+       * When this key was created
+       */
+      createdAt: string;
+
+      /**
+       * User who created this key (usr\_\*)
+       */
+      createdBy: string | null;
+
+      /**
+       * Environment
+       */
+      environment: 'sandbox' | 'prod';
+
+      /**
+       * When this key was last used
+       */
+      lastUsedAt: string | null;
+
+      /**
+       * Human-readable name
+       */
+      name: string;
+
+      /**
+       * When this key was revoked
+       */
+      revokedAt: string | null;
+
+      /**
+       * User who revoked this key (usr\_\*)
+       */
+      revokedBy: string | null;
+
+      /**
+       * Authorized scopes
+       */
+      scopes: Array<string>;
+
+      /**
+       * Status (ACTIVE or REVOKED)
+       */
+      status: 'ACTIVE' | 'REVOKED';
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the API key
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the API key
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
+  }
+}
+
+export interface APIKeyGetResponse {
+  data: APIKeyGetResponse.Data;
+}
+
+export namespace APIKeyGetResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The middle segment
+       * encodes the environment; the final segment is random.
+       */
+      apiKeyPrefix: string;
+
+      /**
+       * When this key was created
+       */
+      createdAt: string;
+
+      /**
+       * User who created this key (usr\_\*)
+       */
+      createdBy: string | null;
+
+      /**
+       * Environment
+       */
+      environment: 'sandbox' | 'prod';
+
+      /**
+       * When this key was last used
+       */
+      lastUsedAt: string | null;
+
+      /**
+       * Human-readable name
+       */
+      name: string;
+
+      /**
+       * When this key was revoked
+       */
+      revokedAt: string | null;
+
+      /**
+       * User who revoked this key (usr\_\*)
+       */
+      revokedBy: string | null;
+
+      /**
+       * Authorized scopes
+       */
+      scopes: Array<string>;
+
+      /**
+       * Status (ACTIVE or REVOKED)
+       */
+      status: 'ACTIVE' | 'REVOKED';
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the API key
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the API key
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface APIKeyRevokeResponse {
+  data: APIKeyRevokeResponse.Data;
+}
+
+export namespace APIKeyRevokeResponse {
+  export interface Data {
+    /**
+     * Resource ID
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The middle segment
+       * encodes the environment; the final segment is random.
+       */
+      apiKeyPrefix: string;
+
+      /**
+       * When this key was created
+       */
+      createdAt: string;
+
+      /**
+       * User who created this key (usr\_\*)
+       */
+      createdBy: string | null;
+
+      /**
+       * Environment
+       */
+      environment: 'sandbox' | 'prod';
+
+      /**
+       * When this key was last used
+       */
+      lastUsedAt: string | null;
+
+      /**
+       * Human-readable name
+       */
+      name: string;
+
+      /**
+       * When this key was revoked
+       */
+      revokedAt: string | null;
+
+      /**
+       * User who revoked this key (usr\_\*)
+       */
+      revokedBy: string | null;
+
+      /**
+       * Authorized scopes
+       */
+      scopes: Array<string>;
+
+      /**
+       * Status (ACTIVE or REVOKED)
+       */
+      status: 'ACTIVE' | 'REVOKED';
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Party that owns the API key
+       */
+      party: Relationships.Party;
+    }
+
+    export namespace Relationships {
+      /**
+       * Party that owns the API key
+       */
+      export interface Party {
+        /**
+         * Related resource identifier
+         */
+        data: Party.Data;
+      }
+
+      export namespace Party {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface APIKeyCreateParams {
+  /**
+   * Body param: Human-readable name for the key
+   */
+  name: string;
+
+  /**
+   * Body param: Permission scopes for the API key. Defaults to all scopes if
+   * omitted.
+   */
+  scopes?: Array<
+    | 'party.read'
+    | 'party.update'
+    | 'invite.read'
+    | 'invite.create'
+    | 'invite.update'
+    | 'invite.delete'
+    | 'membership.create'
+    | 'membership.read'
+    | 'membership.update'
+    | 'membership.delete'
+    | 'payments.create'
+    | 'payments.read'
+    | 'wallets.read'
+    | 'wallets.create'
+    | 'wallets.update'
+    | 'wallets.delete'
+    | 'wallets.fund'
+    | 'wallets.withdraw'
+    | 'delegations.read'
+    | 'delegations.create'
+    | 'delegations.update'
+    | 'delegations.delete'
+    | 'api_keys.read'
+    | 'api_keys.create'
+    | 'api_keys.delete'
+    | 'agents.read'
+    | 'agents.create'
+    | 'agents.update'
+    | 'agents.delete'
+    | 'disputes.read'
+    | 'disputes.create'
+  >;
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface APIKeyListParams {
+  /**
+   * Query param: Cursor for pagination
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Max items per page
+   */
+  limit?: number;
+
+  /**
+   * Query param: Filter by status (ACTIVE or REVOKED)
+   */
+  status?: 'ACTIVE' | 'REVOKED';
+
+  /**
+   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Header param: Required when X-Agent-ID is present. Session or conversation ID
+   * for agent observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface APIKeyGetParams {
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface APIKeyRevokeParams {
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export declare namespace APIKeys {
+  export {
+    type APIKeyCreateResponse as APIKeyCreateResponse,
+    type APIKeyListResponse as APIKeyListResponse,
+    type APIKeyGetResponse as APIKeyGetResponse,
+    type APIKeyRevokeResponse as APIKeyRevokeResponse,
+    type APIKeyCreateParams as APIKeyCreateParams,
+    type APIKeyListParams as APIKeyListParams,
+    type APIKeyGetParams as APIKeyGetParams,
+    type APIKeyRevokeParams as APIKeyRevokeParams,
+  };
+}