@envshed/node 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,375 @@
+interface EnvshedClientOptions {
+    /** API authentication token (envshed_ or envshed_svc_ prefixed) */
+    token: string;
+    /** Base URL for the Envshed API. Defaults to "https://app.envshed.com" */
+    apiUrl?: string;
+    /** Retry configuration for transient failures */
+    retry?: RetryOptions;
+}
+interface RetryOptions {
+    /** Maximum number of retry attempts. Defaults to 3. Set to 0 to disable. */
+    maxRetries?: number;
+    /** Initial delay between retries in ms. Defaults to 1000. */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in ms. Defaults to 10000. */
+    maxDelayMs?: number;
+    /**
+     * Backoff strategy between retries.
+     * - `"exponential"` (default) — delay doubles each attempt: `initialDelayMs * 2^(attempt-1)`
+     * - `"linear"` — constant delay: `initialDelayMs` for every attempt
+     * - `(attempt: number, initialDelayMs: number) => number` — custom function returning delay in ms
+     */
+    backoff?: "exponential" | "linear" | BackoffFunction;
+    /**
+     * Custom function to determine whether a failed request should be retried.
+     * Receives the error and the current attempt number (starting at 1).
+     * Return `true` to retry, `false` to throw immediately.
+     *
+     * Defaults to retrying on 5xx server errors and network errors.
+     *
+     * @example
+     * // Retry on 429 (rate limited) in addition to the defaults
+     * shouldRetry: (error, attempt) => {
+     *   if (error instanceof EnvshedError) return error.status >= 500 || error.status === 429;
+     *   return true; // always retry network errors
+     * }
+     */
+    shouldRetry?: ShouldRetryFunction;
+    /**
+     * Callback invoked before each retry attempt, useful for logging or monitoring.
+     * Receives the error that triggered the retry and the upcoming attempt number.
+     *
+     * @example
+     * onRetry: (error, attempt) => {
+     *   console.warn(`Retry attempt ${attempt}:`, error.message);
+     * }
+     */
+    onRetry?: OnRetryFunction;
+}
+/** Custom backoff function. Receives the attempt number (1-based) and the configured initialDelayMs. Returns the delay in ms before the next retry. */
+type BackoffFunction = (attempt: number, initialDelayMs: number) => number;
+/** Custom function to determine if a request should be retried. Return `true` to retry. */
+type ShouldRetryFunction = (error: Error, attempt: number) => boolean;
+/** Callback invoked before each retry. */
+type OnRetryFunction = (error: Error, attempt: number) => void;
+type TokenScope = "org" | "project" | "environment";
+type TokenPermission = "read" | "read_write";
+/** Coordinates identifying a specific environment */
+interface EnvPath {
+    org: string;
+    project: string;
+    env: string;
+}
+interface GetSecretsResponse {
+    secrets: Record<string, string>;
+    placeholders: string[];
+    version: number;
+    linkedKeys?: string[];
+    decryptErrors?: string[];
+}
+interface SetSecretsRequest {
+    secrets: Record<string, string>;
+}
+interface SetSecretsResponse {
+    ok: true;
+    version: number;
+}
+interface Organization {
+    name: string;
+    slug: string;
+    role: string;
+}
+interface ListOrgsResponse {
+    organizations: Organization[];
+}
+interface CreateOrgRequest {
+    name: string;
+    slug?: string;
+    description?: string;
+}
+interface CreateOrgResponse {
+    organization: {
+        name: string;
+        slug: string;
+    };
+}
+interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+}
+interface ListProjectsResponse {
+    projects: Project[];
+}
+interface CreateProjectRequest {
+    name: string;
+    description?: string;
+}
+interface CreateProjectResponse {
+    project: {
+        name: string;
+        slug: string;
+    };
+}
+interface Environment {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+}
+interface ListEnvironmentsResponse {
+    environments: Environment[];
+}
+interface CreateEnvironmentRequest {
+    name: string;
+    description?: string;
+}
+interface CreateEnvironmentResponse {
+    environment: {
+        name: string;
+        slug: string;
+    };
+}
+interface GetVersionResponse {
+    version: number;
+    updatedAt: string;
+}
+interface SecretVersion {
+    version: number;
+    changeType: string;
+    changedBy: string | null;
+    comment: string | null;
+    createdAt: string;
+}
+interface ListSecretVersionsResponse {
+    versions: SecretVersion[];
+}
+interface ListSecretVersionsOptions {
+    limit?: number;
+    offset?: number;
+}
+interface RollbackSecretResponse {
+    ok: true;
+    newVersion: number;
+}
+interface Snapshot {
+    id: string;
+    name: string | null;
+    description: string | null;
+    createdBy: string | null;
+    createdAt: string;
+}
+interface ListSnapshotsResponse {
+    snapshots: Snapshot[];
+}
+interface CreateSnapshotRequest {
+    name?: string;
+    description?: string;
+}
+interface CreateSnapshotResponse {
+    id: string;
+    name: string | null;
+    createdAt: string;
+}
+interface RestoreSnapshotRequest {
+    snapshotId: string;
+}
+interface RestoreSnapshotResponse {
+    ok: true;
+    restoredCount: number;
+}
+interface MeUserResponse {
+    email: string;
+}
+interface MeServiceTokenResponse {
+    type: "service_token";
+    org: string | null;
+    scope: TokenScope;
+    permission: TokenPermission;
+}
+type MeResponse = MeUserResponse | MeServiceTokenResponse;
+interface ServiceToken {
+    id: string;
+    name: string;
+    description: string | null;
+    token_prefix: string;
+    scope: TokenScope;
+    project_id: string | null;
+    environment_id: string | null;
+    permission: TokenPermission;
+    expires_at: string | null;
+    last_used_at: string | null;
+    is_active: boolean;
+    created_at: string;
+    created_by_email: string;
+    created_by_name: string | null;
+}
+interface ListServiceTokensResponse {
+    tokens: ServiceToken[];
+}
+interface CreateServiceTokenRequest {
+    name: string;
+    description?: string;
+    scope?: TokenScope;
+    projectId?: string;
+    environmentId?: string;
+    permission?: TokenPermission;
+    expiresAt?: string;
+}
+interface CreateServiceTokenResponse {
+    token: string;
+    id: string;
+    name: string;
+}
+interface DeleteServiceTokenResponse {
+    ok: true;
+}
+/** @internal */
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number>;
+}
+
+declare class EnvshedClient {
+    private readonly token;
+    private readonly apiUrl;
+    private readonly retryConfig;
+    /** Manage secrets in an environment */
+    readonly secrets: SecretsAPI;
+    /** Manage organizations */
+    readonly orgs: OrgsAPI;
+    /** Manage projects within an organization */
+    readonly projects: ProjectsAPI;
+    /** Manage environments within a project */
+    readonly environments: EnvironmentsAPI;
+    /** Query environment version (supports ETag) */
+    readonly version: VersionAPI;
+    /** Manage secret version history and rollbacks */
+    readonly versions: VersionsAPI;
+    /** Manage environment snapshots */
+    readonly snapshots: SnapshotsAPI;
+    /** Manage service tokens (admin only) */
+    readonly serviceTokens: ServiceTokensAPI;
+    constructor(options: EnvshedClientOptions);
+    /** Check authentication and return current user/token info */
+    me(): Promise<MeResponse>;
+    /** @internal */
+    _request<T>(options: RequestOptions): Promise<T>;
+}
+declare class SecretsAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** Get all secrets for an environment */
+    get(path: EnvPath): Promise<GetSecretsResponse>;
+    /** Set (upsert) secrets for an environment */
+    set(path: EnvPath, secrets: Record<string, string>): Promise<SetSecretsResponse>;
+}
+declare class OrgsAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** List all organizations the authenticated user belongs to */
+    list(): Promise<ListOrgsResponse>;
+    /** Create a new organization */
+    create(data: CreateOrgRequest): Promise<CreateOrgResponse>;
+}
+declare class ProjectsAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** List all projects in an organization */
+    list(org: string): Promise<ListProjectsResponse>;
+    /** Create a new project in an organization */
+    create(org: string, data: CreateProjectRequest): Promise<CreateProjectResponse>;
+}
+declare class EnvironmentsAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** List all environments in a project */
+    list(org: string, project: string): Promise<ListEnvironmentsResponse>;
+    /** Create a new environment in a project */
+    create(org: string, project: string, data: CreateEnvironmentRequest): Promise<CreateEnvironmentResponse>;
+}
+declare class VersionAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** Get the current version of an environment. Returns null if unchanged (304). */
+    get(path: EnvPath, etag?: string): Promise<GetVersionResponse | null>;
+}
+declare class VersionsAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** List version history for a specific secret key */
+    list(path: EnvPath, secretKey: string, options?: ListSecretVersionsOptions): Promise<ListSecretVersionsResponse>;
+    /** Rollback a secret to a previous version */
+    rollback(path: EnvPath, secretKey: string, targetVersion: number): Promise<RollbackSecretResponse>;
+}
+declare class SnapshotsAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** List all snapshots for an environment */
+    list(path: EnvPath): Promise<ListSnapshotsResponse>;
+    /** Create a snapshot of the current environment state */
+    create(path: EnvPath, data?: CreateSnapshotRequest): Promise<CreateSnapshotResponse>;
+    /** Restore an environment from a snapshot */
+    restore(path: EnvPath, snapshotId: string): Promise<RestoreSnapshotResponse>;
+}
+declare class ServiceTokensAPI {
+    private readonly client;
+    constructor(client: EnvshedClient);
+    /** List all service tokens for an organization (admin only) */
+    list(org: string): Promise<ListServiceTokensResponse>;
+    /** Create a new service token (admin only) */
+    create(org: string, data: CreateServiceTokenRequest): Promise<CreateServiceTokenResponse>;
+    /** Delete a service token (admin only) */
+    delete(org: string, tokenId: string): Promise<DeleteServiceTokenResponse>;
+}
+
+/**
+ * Error thrown when the Envshed API returns an HTTP error response (4xx or 5xx).
+ */
+declare class EnvshedError extends Error {
+    /** HTTP status code from the API */
+    readonly status: number;
+    /** Error message from the API response body */
+    readonly apiMessage: string;
+    /** HTTP method of the failed request */
+    readonly method: string;
+    /** URL path of the failed request */
+    readonly path: string;
+    constructor(options: {
+        status: number;
+        apiMessage: string;
+        method: string;
+        path: string;
+    });
+    /** Whether this is an authentication error (401) */
+    get isUnauthorized(): boolean;
+    /** Whether this is a permissions error (403) */
+    get isForbidden(): boolean;
+    /** Whether this is a not found error (404) */
+    get isNotFound(): boolean;
+    /** Whether this is a subscription-related error (402) */
+    get isSubscriptionRequired(): boolean;
+    /** Whether this error is retryable (5xx server errors) */
+    get isRetryable(): boolean;
+}
+/**
+ * Error thrown when a network-level failure occurs (no HTTP response).
+ * Always considered retryable.
+ */
+declare class EnvshedNetworkError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly cause: Error;
+    constructor(options: {
+        method: string;
+        path: string;
+        cause: Error;
+    });
+    get isRetryable(): boolean;
+}
+
+export { type BackoffFunction, type CreateEnvironmentRequest, type CreateEnvironmentResponse, type CreateOrgRequest, type CreateOrgResponse, type CreateProjectRequest, type CreateProjectResponse, type CreateServiceTokenRequest, type CreateServiceTokenResponse, type CreateSnapshotRequest, type CreateSnapshotResponse, type DeleteServiceTokenResponse, type EnvPath, type Environment, EnvshedClient, type EnvshedClientOptions, EnvshedError, EnvshedNetworkError, type GetSecretsResponse, type GetVersionResponse, type ListEnvironmentsResponse, type ListOrgsResponse, type ListProjectsResponse, type ListSecretVersionsOptions, type ListSecretVersionsResponse, type ListServiceTokensResponse, type ListSnapshotsResponse, type MeResponse, type MeServiceTokenResponse, type MeUserResponse, type OnRetryFunction, type Organization, type Project, type RestoreSnapshotRequest, type RestoreSnapshotResponse, type RetryOptions, type RollbackSecretResponse, type SecretVersion, type ServiceToken, type SetSecretsRequest, type SetSecretsResponse, type ShouldRetryFunction, type Snapshot, type TokenPermission, type TokenScope };