keyenv 0.1.0 → 1.1.1

package/README.md

@@ -103,6 +103,19 @@ for (const env of project.environments) {
 }
 ```
 
+### Service Token Info
+
+```typescript
+// Get current user or service token info
+const user = await client.getCurrentUser();
+
+if (user.auth_type === 'service_token') {
+  // Service tokens can access multiple projects
+  console.log('Projects:', user.project_ids);
+  console.log('Scopes:', user.scopes);
+}
+```
+
 ## Error Handling
 
 ```typescript
@@ -156,6 +169,12 @@ Create a new KeyEnv client.
 | `bulkImport(projectId, env, secrets)` | Bulk import secrets |
 | `loadEnv(projectId, env)` | Load secrets into process.env |
 | `generateEnvFile(projectId, env)` | Generate .env file content |
+| `listPermissions(projectId, env)` | List permissions for an environment |
+| `setPermission(projectId, env, userId, role)` | Set user's permission |
+| `deletePermission(projectId, env, userId)` | Delete user's permission |
+| `getMyPermissions(projectId)` | Get current user's permissions |
+| `getProjectDefaults(projectId)` | Get default permissions |
+| `setProjectDefaults(projectId, defaults)` | Set default permissions |
 
 ## License
 

package/dist/index.d.mts

@@ -4,6 +4,10 @@ interface KeyEnvOptions {
     token: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Cache TTL in seconds for exportSecrets/loadEnv (default: 0 = disabled). Also configurable via KEYENV_CACHE_TTL env var. */
+    cacheTtl?: number;
+    /** Custom API base URL (default: https://api.keyenv.dev). Also configurable via KEYENV_API_URL env var. */
+    baseUrl?: string;
 }
 /** User or service token info */
 interface User {
@@ -16,8 +20,8 @@ interface User {
     auth_type?: 'service_token' | 'user';
     /** Team ID (for service tokens) */
     team_id?: string;
-    /** Project ID (for project-scoped service tokens) */
-    project_id?: string;
+    /** Project IDs (for project-scoped service tokens) */
+    project_ids?: string[];
     /** Token scopes (for service tokens) */
     scopes?: string[];
     created_at: string;
@@ -87,6 +91,42 @@ declare class KeyEnvError extends Error {
     readonly details?: Record<string, unknown>;
     constructor(message: string, status: number, code?: string, details?: Record<string, unknown>);
 }
+/** Environment permission role */
+type EnvironmentRole = 'none' | 'read' | 'write' | 'admin';
+/** Environment permission for a user */
+interface EnvironmentPermission {
+    id: string;
+    environment_id: string;
+    user_id: string;
+    role: EnvironmentRole;
+    user_email?: string;
+    user_name?: string;
+    granted_by?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** User's permission for an environment */
+interface MyPermission {
+    environment_id: string;
+    environment_name: string;
+    role: EnvironmentRole;
+    can_read: boolean;
+    can_write: boolean;
+    can_admin: boolean;
+}
+/** Response for getting user's permissions */
+interface MyPermissionsResponse {
+    permissions: MyPermission[];
+    is_team_admin: boolean;
+}
+/** Project default permission for an environment */
+interface ProjectDefault {
+    id: string;
+    project_id: string;
+    environment_name: string;
+    default_role: EnvironmentRole;
+    created_at: string;
+}
 
 /**
  * KeyEnv API client for managing secrets
@@ -103,7 +143,10 @@ declare class KeyEnvError extends Error {
  */
 declare class KeyEnv {
     private readonly token;
+    private readonly baseUrl;
     private readonly timeout;
+    private readonly cacheTtl;
+    private readonly secretsCache;
     constructor(options: KeyEnvOptions);
     private request;
     /** Get the current user or service token info */
@@ -127,7 +170,8 @@ declare class KeyEnv {
     /** List secrets in an environment (keys and metadata only) */
     listSecrets(projectId: string, environment: string): Promise<Secret[]>;
     /**
-     * Export all secrets with their decrypted values
+     * Export all secrets with their decrypted values.
+     * Results are cached when cacheTtl > 0.
      * @example
      * ```ts
      * const secrets = await client.exportSecrets('project-id', 'production');
@@ -182,6 +226,112 @@ declare class KeyEnv {
     loadEnv(projectId: string, environment: string): Promise<number>;
     /** Generate .env file content from secrets */
     generateEnvFile(projectId: string, environment: string): Promise<string>;
+    /**
+     * Clear the secrets cache.
+     * @param projectId - Clear cache for specific project (optional)
+     * @param environment - Clear cache for specific environment (requires projectId)
+     */
+    clearCache(projectId?: string, environment?: string): void;
+    /**
+     * List all permissions for an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @returns Array of environment permissions
+     * @example
+     * ```ts
+     * const permissions = await client.listPermissions('project-id', 'production');
+     * for (const perm of permissions) {
+     *   console.log(`${perm.user_email}: ${perm.role}`);
+     * }
+     * ```
+     */
+    listPermissions(projectId: string, environment: string): Promise<EnvironmentPermission[]>;
+    /**
+     * Set a user's permission for an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @param userId - The user ID to set permission for
+     * @param role - The permission role ('none', 'read', 'write', or 'admin')
+     * @returns The created or updated permission
+     * @example
+     * ```ts
+     * const permission = await client.setPermission('project-id', 'production', 'user-id', 'write');
+     * console.log(`Set ${permission.user_email} to ${permission.role}`);
+     * ```
+     */
+    setPermission(projectId: string, environment: string, userId: string, role: EnvironmentRole): Promise<EnvironmentPermission>;
+    /**
+     * Delete a user's permission for an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @param userId - The user ID to delete permission for
+     * @example
+     * ```ts
+     * await client.deletePermission('project-id', 'production', 'user-id');
+     * ```
+     */
+    deletePermission(projectId: string, environment: string, userId: string): Promise<void>;
+    /**
+     * Bulk set permissions for multiple users in an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @param permissions - Array of user permissions to set
+     * @returns Array of created or updated permissions
+     * @example
+     * ```ts
+     * const permissions = await client.bulkSetPermissions('project-id', 'production', [
+     *   { userId: 'user-1', role: 'write' },
+     *   { userId: 'user-2', role: 'read' },
+     * ]);
+     * ```
+     */
+    bulkSetPermissions(projectId: string, environment: string, permissions: Array<{
+        userId: string;
+        role: EnvironmentRole;
+    }>): Promise<EnvironmentPermission[]>;
+    /**
+     * Get the current user's permissions for all environments in a project.
+     * @param projectId - The project ID
+     * @returns The user's permissions and team admin status
+     * @example
+     * ```ts
+     * const { permissions, is_team_admin } = await client.getMyPermissions('project-id');
+     * for (const perm of permissions) {
+     *   console.log(`${perm.environment_name}: ${perm.role} (can_write: ${perm.can_write})`);
+     * }
+     * ```
+     */
+    getMyPermissions(projectId: string): Promise<MyPermissionsResponse>;
+    /**
+     * Get default permission settings for a project's environments.
+     * @param projectId - The project ID
+     * @returns Array of project default permissions
+     * @example
+     * ```ts
+     * const defaults = await client.getProjectDefaults('project-id');
+     * for (const def of defaults) {
+     *   console.log(`${def.environment_name}: ${def.default_role}`);
+     * }
+     * ```
+     */
+    getProjectDefaults(projectId: string): Promise<ProjectDefault[]>;
+    /**
+     * Set default permission settings for a project's environments.
+     * @param projectId - The project ID
+     * @param defaults - Array of default permissions to set
+     * @returns Array of updated project default permissions
+     * @example
+     * ```ts
+     * const defaults = await client.setProjectDefaults('project-id', [
+     *   { environmentName: 'development', defaultRole: 'write' },
+     *   { environmentName: 'production', defaultRole: 'read' },
+     * ]);
+     * ```
+     */
+    setProjectDefaults(projectId: string, defaults: Array<{
+        environmentName: string;
+        defaultRole: EnvironmentRole;
+    }>): Promise<ProjectDefault[]>;
 }
 
-export { type BulkImportResult, type BulkSecretItem, type Environment, KeyEnv, KeyEnvError, type KeyEnvOptions, type Project, type ProjectWithEnvironments, type Secret, type SecretHistory, type SecretWithValue, type User };
+export { type BulkImportResult, type BulkSecretItem, type Environment, type EnvironmentPermission, type EnvironmentRole, KeyEnv, KeyEnvError, type KeyEnvOptions, type MyPermission, type MyPermissionsResponse, type Project, type ProjectDefault, type ProjectWithEnvironments, type Secret, type SecretHistory, type SecretWithValue, type User };

package/dist/index.d.ts

@@ -4,6 +4,10 @@ interface KeyEnvOptions {
     token: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Cache TTL in seconds for exportSecrets/loadEnv (default: 0 = disabled). Also configurable via KEYENV_CACHE_TTL env var. */
+    cacheTtl?: number;
+    /** Custom API base URL (default: https://api.keyenv.dev). Also configurable via KEYENV_API_URL env var. */
+    baseUrl?: string;
 }
 /** User or service token info */
 interface User {
@@ -16,8 +20,8 @@ interface User {
     auth_type?: 'service_token' | 'user';
     /** Team ID (for service tokens) */
     team_id?: string;
-    /** Project ID (for project-scoped service tokens) */
-    project_id?: string;
+    /** Project IDs (for project-scoped service tokens) */
+    project_ids?: string[];
     /** Token scopes (for service tokens) */
     scopes?: string[];
     created_at: string;
@@ -87,6 +91,42 @@ declare class KeyEnvError extends Error {
     readonly details?: Record<string, unknown>;
     constructor(message: string, status: number, code?: string, details?: Record<string, unknown>);
 }
+/** Environment permission role */
+type EnvironmentRole = 'none' | 'read' | 'write' | 'admin';
+/** Environment permission for a user */
+interface EnvironmentPermission {
+    id: string;
+    environment_id: string;
+    user_id: string;
+    role: EnvironmentRole;
+    user_email?: string;
+    user_name?: string;
+    granted_by?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** User's permission for an environment */
+interface MyPermission {
+    environment_id: string;
+    environment_name: string;
+    role: EnvironmentRole;
+    can_read: boolean;
+    can_write: boolean;
+    can_admin: boolean;
+}
+/** Response for getting user's permissions */
+interface MyPermissionsResponse {
+    permissions: MyPermission[];
+    is_team_admin: boolean;
+}
+/** Project default permission for an environment */
+interface ProjectDefault {
+    id: string;
+    project_id: string;
+    environment_name: string;
+    default_role: EnvironmentRole;
+    created_at: string;
+}
 
 /**
  * KeyEnv API client for managing secrets
@@ -103,7 +143,10 @@ declare class KeyEnvError extends Error {
  */
 declare class KeyEnv {
     private readonly token;
+    private readonly baseUrl;
     private readonly timeout;
+    private readonly cacheTtl;
+    private readonly secretsCache;
     constructor(options: KeyEnvOptions);
     private request;
     /** Get the current user or service token info */
@@ -127,7 +170,8 @@ declare class KeyEnv {
     /** List secrets in an environment (keys and metadata only) */
     listSecrets(projectId: string, environment: string): Promise<Secret[]>;
     /**
-     * Export all secrets with their decrypted values
+     * Export all secrets with their decrypted values.
+     * Results are cached when cacheTtl > 0.
      * @example
      * ```ts
      * const secrets = await client.exportSecrets('project-id', 'production');
@@ -182,6 +226,112 @@ declare class KeyEnv {
     loadEnv(projectId: string, environment: string): Promise<number>;
     /** Generate .env file content from secrets */
     generateEnvFile(projectId: string, environment: string): Promise<string>;
+    /**
+     * Clear the secrets cache.
+     * @param projectId - Clear cache for specific project (optional)
+     * @param environment - Clear cache for specific environment (requires projectId)
+     */
+    clearCache(projectId?: string, environment?: string): void;
+    /**
+     * List all permissions for an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @returns Array of environment permissions
+     * @example
+     * ```ts
+     * const permissions = await client.listPermissions('project-id', 'production');
+     * for (const perm of permissions) {
+     *   console.log(`${perm.user_email}: ${perm.role}`);
+     * }
+     * ```
+     */
+    listPermissions(projectId: string, environment: string): Promise<EnvironmentPermission[]>;
+    /**
+     * Set a user's permission for an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @param userId - The user ID to set permission for
+     * @param role - The permission role ('none', 'read', 'write', or 'admin')
+     * @returns The created or updated permission
+     * @example
+     * ```ts
+     * const permission = await client.setPermission('project-id', 'production', 'user-id', 'write');
+     * console.log(`Set ${permission.user_email} to ${permission.role}`);
+     * ```
+     */
+    setPermission(projectId: string, environment: string, userId: string, role: EnvironmentRole): Promise<EnvironmentPermission>;
+    /**
+     * Delete a user's permission for an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @param userId - The user ID to delete permission for
+     * @example
+     * ```ts
+     * await client.deletePermission('project-id', 'production', 'user-id');
+     * ```
+     */
+    deletePermission(projectId: string, environment: string, userId: string): Promise<void>;
+    /**
+     * Bulk set permissions for multiple users in an environment.
+     * @param projectId - The project ID
+     * @param environment - The environment name
+     * @param permissions - Array of user permissions to set
+     * @returns Array of created or updated permissions
+     * @example
+     * ```ts
+     * const permissions = await client.bulkSetPermissions('project-id', 'production', [
+     *   { userId: 'user-1', role: 'write' },
+     *   { userId: 'user-2', role: 'read' },
+     * ]);
+     * ```
+     */
+    bulkSetPermissions(projectId: string, environment: string, permissions: Array<{
+        userId: string;
+        role: EnvironmentRole;
+    }>): Promise<EnvironmentPermission[]>;
+    /**
+     * Get the current user's permissions for all environments in a project.
+     * @param projectId - The project ID
+     * @returns The user's permissions and team admin status
+     * @example
+     * ```ts
+     * const { permissions, is_team_admin } = await client.getMyPermissions('project-id');
+     * for (const perm of permissions) {
+     *   console.log(`${perm.environment_name}: ${perm.role} (can_write: ${perm.can_write})`);
+     * }
+     * ```
+     */
+    getMyPermissions(projectId: string): Promise<MyPermissionsResponse>;
+    /**
+     * Get default permission settings for a project's environments.
+     * @param projectId - The project ID
+     * @returns Array of project default permissions
+     * @example
+     * ```ts
+     * const defaults = await client.getProjectDefaults('project-id');
+     * for (const def of defaults) {
+     *   console.log(`${def.environment_name}: ${def.default_role}`);
+     * }
+     * ```
+     */
+    getProjectDefaults(projectId: string): Promise<ProjectDefault[]>;
+    /**
+     * Set default permission settings for a project's environments.
+     * @param projectId - The project ID
+     * @param defaults - Array of default permissions to set
+     * @returns Array of updated project default permissions
+     * @example
+     * ```ts
+     * const defaults = await client.setProjectDefaults('project-id', [
+     *   { environmentName: 'development', defaultRole: 'write' },
+     *   { environmentName: 'production', defaultRole: 'read' },
+     * ]);
+     * ```
+     */
+    setProjectDefaults(projectId: string, defaults: Array<{
+        environmentName: string;
+        defaultRole: EnvironmentRole;
+    }>): Promise<ProjectDefault[]>;
 }
 
-export { type BulkImportResult, type BulkSecretItem, type Environment, KeyEnv, KeyEnvError, type KeyEnvOptions, type Project, type ProjectWithEnvironments, type Secret, type SecretHistory, type SecretWithValue, type User };
+export { type BulkImportResult, type BulkSecretItem, type Environment, type EnvironmentPermission, type EnvironmentRole, KeyEnv, KeyEnvError, type KeyEnvOptions, type MyPermission, type MyPermissionsResponse, type Project, type ProjectDefault, type ProjectWithEnvironments, type Secret, type SecretHistory, type SecretWithValue, type User };