@hypercerts-org/sdk-core 0.9.0-beta.0 → 0.10.0-beta.0

package/dist/testing.d.ts

@@ -366,7 +366,32 @@ declare const OAuthConfigSchema: z.ZodObject<{
     redirectUri: z.ZodString;
     /**
      * OAuth scopes to request, space-separated.
-     * Common scopes: "atproto", "transition:generic"
+     *
+     * Can be a string of space-separated permissions or use the permission system:
+     *
+     * @example Using presets
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     * scope: ScopePresets.EMAIL_AND_PROFILE
+     * ```
+     *
+     * @example Building custom scopes
+     * ```typescript
+     * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+     * scope: buildScope(
+     *   new PermissionBuilder()
+     *     .accountEmail('read')
+     *     .repoWrite('app.bsky.feed.post')
+     *     .build()
+     * )
+     * ```
+     *
+     * @example Legacy scopes
+     * ```typescript
+     * scope: "atproto transition:generic"
+     * ```
+     *
+     * @see https://atproto.com/specs/permission for permission details
      */
     scope: z.ZodString;
     /**

package/dist/types.cjs

@@ -24,9 +24,34 @@ const OAuthConfigSchema = zod.z.object({
     redirectUri: zod.z.string().url(),
     /**
      * OAuth scopes to request, space-separated.
-     * Common scopes: "atproto", "transition:generic"
+     *
+     * Can be a string of space-separated permissions or use the permission system:
+     *
+     * @example Using presets
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     * scope: ScopePresets.EMAIL_AND_PROFILE
+     * ```
+     *
+     * @example Building custom scopes
+     * ```typescript
+     * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+     * scope: buildScope(
+     *   new PermissionBuilder()
+     *     .accountEmail('read')
+     *     .repoWrite('app.bsky.feed.post')
+     *     .build()
+     * )
+     * ```
+     *
+     * @example Legacy scopes
+     * ```typescript
+     * scope: "atproto transition:generic"
+     * ```
+     *
+     * @see https://atproto.com/specs/permission for permission details
      */
-    scope: zod.z.string(),
+    scope: zod.z.string().min(1, "OAuth scope is required"),
     /**
      * URL to your public JWKS (JSON Web Key Set) endpoint.
      * Used by the authorization server to verify your client's signatures.

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.cjs","sources":["../src/core/config.ts","../src/core/types.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { SessionStore, StateStore, CacheInterface, LoggerInterface } from \"./interfaces.js\";\n\n/**\n * Zod schema for OAuth configuration validation.\n *\n * @remarks\n * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field\n * should contain the private key in JWK (JSON Web Key) format as a string.\n */\nexport const OAuthConfigSchema = z.object({\n  /**\n   * URL to the OAuth client metadata JSON document.\n   * This document describes your application to the authorization server.\n   *\n   * @see https://atproto.com/specs/oauth#client-metadata\n   */\n  clientId: z.string().url(),\n\n  /**\n   * URL where users are redirected after authentication.\n   * Must match one of the redirect URIs in your client metadata.\n   */\n  redirectUri: z.string().url(),\n\n  /**\n   * OAuth scopes to request, space-separated.\n   * Common scopes: \"atproto\", \"transition:generic\"\n   */\n  scope: z.string(),\n\n  /**\n   * URL to your public JWKS (JSON Web Key Set) endpoint.\n   * Used by the authorization server to verify your client's signatures.\n   */\n  jwksUri: z.string().url(),\n\n  /**\n   * Private JWK (JSON Web Key) as a JSON string.\n   * Used for signing DPoP proofs and client assertions.\n   *\n   * @remarks\n   * This should be kept secret and never exposed to clients.\n   * Typically loaded from environment variables or a secrets manager.\n   */\n  jwkPrivate: z.string(),\n});\n\n/**\n * Zod schema for server URL configuration.\n *\n * @remarks\n * At least one server (PDS or SDS) should be configured for the SDK to be useful.\n */\nexport const ServerConfigSchema = z.object({\n  /**\n   * Personal Data Server URL - the user's own AT Protocol server.\n   * This is the primary server for user data operations.\n   *\n   * @example \"https://bsky.social\"\n   */\n  pds: z.string().url().optional(),\n\n  /**\n   * Shared Data Server URL - for collaborative data storage.\n   * Required for collaborator and organization operations.\n   *\n   * @example \"https://sds.hypercerts.org\"\n   */\n  sds: z.string().url().optional(),\n});\n\n/**\n * Zod schema for timeout configuration.\n *\n * @remarks\n * All timeout values are in milliseconds.\n */\nexport const TimeoutConfigSchema = z.object({\n  /**\n   * Timeout for fetching PDS metadata during identity resolution.\n   * @default 5000 (5 seconds, set by OAuthClient)\n   */\n  pdsMetadata: z.number().positive().optional(),\n\n  /**\n   * Timeout for general API requests to PDS/SDS.\n   * @default 30000 (30 seconds)\n   */\n  apiRequests: z.number().positive().optional(),\n});\n\n/**\n * Zod schema for SDK configuration validation.\n *\n * @remarks\n * This schema validates only the primitive/serializable parts of the configuration.\n * Storage interfaces ({@link SessionStore}, {@link StateStore}) cannot be validated\n * with Zod as they are runtime objects.\n */\nexport const ATProtoSDKConfigSchema = z.object({\n  oauth: OAuthConfigSchema,\n  servers: ServerConfigSchema.optional(),\n  timeouts: TimeoutConfigSchema.optional(),\n});\n\n/**\n * Configuration options for the ATProto SDK.\n *\n * This interface defines all configuration needed to initialize the SDK,\n * including OAuth credentials, server endpoints, and optional customizations.\n *\n * @example Minimal configuration\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: {\n *     clientId: \"https://my-app.com/client-metadata.json\",\n *     redirectUri: \"https://my-app.com/callback\",\n *     scope: \"atproto transition:generic\",\n *     jwksUri: \"https://my-app.com/.well-known/jwks.json\",\n *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,\n *   },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *   },\n * };\n * ```\n *\n * @example Full configuration with custom storage\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: { ... },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *     sds: \"https://sds.hypercerts.org\",\n *   },\n *   storage: {\n *     sessionStore: new RedisSessionStore(redisClient),\n *     stateStore: new RedisStateStore(redisClient),\n *   },\n *   timeouts: {\n *     pdsMetadata: 5000,\n *     apiRequests: 30000,\n *   },\n *   logger: console,\n * };\n * ```\n */\nexport interface ATProtoSDKConfig {\n  /**\n   * OAuth 2.0 configuration for authentication.\n   *\n   * Required fields for the OAuth flow with DPoP (Demonstrating Proof of Possession).\n   * Your application must host the client metadata and JWKS endpoints.\n   *\n   * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification\n   */\n  oauth: z.infer<typeof OAuthConfigSchema>;\n\n  /**\n   * Server URLs for PDS and SDS connections.\n   *\n   * - **PDS**: Personal Data Server - user's own data storage\n   * - **SDS**: Shared Data Server - collaborative storage with access control\n   */\n  servers?: z.infer<typeof ServerConfigSchema>;\n\n  /**\n   * Storage adapters for persisting OAuth sessions and state.\n   *\n   * If not provided, in-memory implementations are used automatically.\n   * **Warning**: In-memory storage is lost on process restart - use persistent\n   * storage (Redis, database, etc.) in production.\n   *\n   * @example\n   * ```typescript\n   * storage: {\n   *   sessionStore: new RedisSessionStore(redis),\n   *   stateStore: new RedisStateStore(redis),\n   * }\n   * ```\n   */\n  storage?: {\n    /**\n     * Persistent storage for OAuth sessions.\n     * Sessions contain access tokens, refresh tokens, and DPoP keys.\n     */\n    sessionStore?: SessionStore;\n\n    /**\n     * Temporary storage for OAuth state during the authorization flow.\n     * State is short-lived and used for PKCE and CSRF protection.\n     */\n    stateStore?: StateStore;\n  };\n\n  /**\n   * Custom fetch implementation for HTTP requests.\n   *\n   * Use this to add custom headers, logging, or to use a different HTTP client.\n   * Must be compatible with the standard Fetch API.\n   *\n   * @example\n   * ```typescript\n   * fetch: async (url, init) => {\n   *   console.log(`Fetching: ${url}`);\n   *   return globalThis.fetch(url, init);\n   * }\n   * ```\n   */\n  fetch?: typeof fetch;\n\n  /**\n   * Timeout configuration for network requests.\n   * Values are in milliseconds.\n   */\n  timeouts?: z.infer<typeof TimeoutConfigSchema>;\n\n  /**\n   * Cache for profiles, metadata, and other frequently accessed data.\n   *\n   * Implementing caching can significantly reduce API calls and improve performance.\n   * The SDK does not provide a default cache - you must implement {@link CacheInterface}.\n   */\n  cache?: CacheInterface;\n\n  /**\n   * Logger for debugging and observability.\n   *\n   * The logger receives debug, info, warn, and error messages from the SDK.\n   * Compatible with `console` or any logger implementing {@link LoggerInterface}.\n   *\n   * @example\n   * ```typescript\n   * logger: console\n   * // or\n   * logger: pino()\n   * // or\n   * logger: winston.createLogger({ ... })\n   * ```\n   */\n  logger?: LoggerInterface;\n}\n","import type { OAuthSession } from \"@atproto/oauth-client-node\";\nimport { z } from \"zod\";\n\n/**\n * Decentralized Identifier (DID) - a unique, persistent identifier for AT Protocol users.\n *\n * DIDs are the canonical identifier for users in the AT Protocol ecosystem.\n * Unlike handles which can change, DIDs remain constant for the lifetime of an account.\n *\n * @remarks\n * AT Protocol supports multiple DID methods:\n * - `did:plc:` - PLC (Public Ledger of Credentials) DIDs, most common for Bluesky users\n * - `did:web:` - Web DIDs, resolved via HTTPS\n *\n * @example\n * ```typescript\n * const did: DID = \"did:plc:ewvi7nxzyoun6zhxrhs64oiz\";\n * const webDid: DID = \"did:web:example.com\";\n * ```\n *\n * @see https://atproto.com/specs/did for DID specification\n */\nexport type DID = string;\n\n/**\n * OAuth session with DPoP (Demonstrating Proof of Possession) support.\n *\n * This type represents an authenticated user session. It wraps the\n * `@atproto/oauth-client-node` OAuthSession and contains:\n * - Access token for API requests\n * - Refresh token for obtaining new access tokens\n * - DPoP key pair for proof-of-possession\n * - User's DID and other identity information\n *\n * @remarks\n * Sessions are managed by the SDK and automatically refresh when tokens expire.\n * Store the user's DID to restore sessions later with {@link ATProtoSDK.restoreSession}.\n *\n * Key properties from OAuthSession:\n * - `did` or `sub`: The user's DID\n * - `handle`: The user's handle (e.g., \"user.bsky.social\")\n *\n * @example\n * ```typescript\n * const session = await sdk.callback(params);\n *\n * // Access user identity\n * console.log(`Logged in as: ${session.did}`);\n *\n * // Use session for repository operations\n * const repo = sdk.repository(session);\n * ```\n *\n * @see https://atproto.com/specs/oauth for OAuth specification\n */\nexport type Session = OAuthSession;\n\n/**\n * Zod schema for collaborator permissions in SDS repositories.\n *\n * Defines the granular permissions a collaborator can have on a shared repository.\n * Permissions follow a hierarchical model where higher-level permissions\n * typically imply lower-level ones.\n */\nexport const CollaboratorPermissionsSchema = z.object({\n  /**\n   * Can read/view records in the repository.\n   * This is the most basic permission level.\n   */\n  read: z.boolean(),\n\n  /**\n   * Can create new records in the repository.\n   * Typically implies `read` permission.\n   */\n  create: z.boolean(),\n\n  /**\n   * Can modify existing records in the repository.\n   * Typically implies `read` and `create` permissions.\n   */\n  update: z.boolean(),\n\n  /**\n   * Can delete records from the repository.\n   * Typically implies `read`, `create`, and `update` permissions.\n   */\n  delete: z.boolean(),\n\n  /**\n   * Can manage collaborators and their permissions.\n   * Administrative permission that allows inviting/removing collaborators.\n   */\n  admin: z.boolean(),\n\n  /**\n   * Full ownership of the repository.\n   * Owners have all permissions and cannot be removed by other admins.\n   * There must always be at least one owner.\n   */\n  owner: z.boolean(),\n});\n\n/**\n * Collaborator permissions for SDS (Shared Data Server) repositories.\n *\n * These permissions control what actions a collaborator can perform\n * on records within a shared repository.\n *\n * @example\n * ```typescript\n * // Read-only collaborator\n * const readOnlyPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: false,\n *   update: false,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Editor collaborator\n * const editorPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Admin collaborator\n * const adminPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: true,\n *   admin: true,\n *   owner: false,\n * };\n * ```\n */\nexport type CollaboratorPermissions = z.infer<typeof CollaboratorPermissionsSchema>;\n\n/**\n * Zod schema for SDS organization data.\n *\n * Organizations are top-level entities in SDS that can own repositories\n * and have multiple collaborators with different permission levels.\n */\nexport const OrganizationSchema = z.object({\n  /**\n   * The organization's DID - unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  did: z.string(),\n\n  /**\n   * The organization's handle - human-readable identifier.\n   * Format: \"orgname.sds.hypercerts.org\" or similar\n   */\n  handle: z.string(),\n\n  /**\n   * Display name for the organization.\n   */\n  name: z.string(),\n\n  /**\n   * Optional description of the organization's purpose.\n   */\n  description: z.string().optional(),\n\n  /**\n   * ISO 8601 timestamp when the organization was created.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  createdAt: z.string(),\n\n  /**\n   * The current user's permissions within this organization.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * How the current user relates to this organization.\n   * - `\"owner\"`: User created or owns the organization\n   * - `\"shared\"`: User was invited to collaborate (has permissions)\n   * - `\"none\"`: User has no access to this organization\n   */\n  accessType: z.enum([\"owner\", \"shared\", \"none\"]),\n});\n\n/**\n * SDS Organization entity.\n *\n * Represents an organization on a Shared Data Server. Organizations\n * provide a way to group repositories and manage access for teams.\n *\n * @example\n * ```typescript\n * const org: Organization = {\n *   did: \"did:plc:org123abc\",\n *   handle: \"my-team.sds.hypercerts.org\",\n *   name: \"My Team\",\n *   description: \"A team working on impact certificates\",\n *   createdAt: \"2024-01-15T10:30:00.000Z\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: true,\n *     admin: true,\n *     owner: true,\n *   },\n *   accessType: \"owner\",\n * };\n * ```\n */\nexport type Organization = z.infer<typeof OrganizationSchema>;\n\n/**\n * Zod schema for collaborator data.\n *\n * Represents a user who has been granted access to a shared repository\n * or organization with specific permissions.\n */\nexport const CollaboratorSchema = z.object({\n  /**\n   * The collaborator's DID - their unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  userDid: z.string(),\n\n  /**\n   * The permissions granted to this collaborator.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * DID of the user who granted these permissions.\n   * Useful for audit trails.\n   */\n  grantedBy: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were granted.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  grantedAt: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were revoked, if applicable.\n   * Undefined if the collaborator is still active.\n   */\n  revokedAt: z.string().optional(),\n});\n\n/**\n * Collaborator information for SDS repositories.\n *\n * Represents a user who has been granted access to collaborate on\n * a shared repository or organization.\n *\n * @example\n * ```typescript\n * const collaborator: Collaborator = {\n *   userDid: \"did:plc:user456def\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: false,\n *     admin: false,\n *     owner: false,\n *   },\n *   grantedBy: \"did:plc:owner123abc\",\n *   grantedAt: \"2024-02-01T14:00:00.000Z\",\n * };\n * ```\n */\nexport type Collaborator = z.infer<typeof CollaboratorSchema>;\n"],"names":["z"],"mappings":"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"}
+{"version":3,"file":"types.cjs","sources":["../src/core/config.ts","../src/core/types.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { SessionStore, StateStore, CacheInterface, LoggerInterface } from \"./interfaces.js\";\n\n/**\n * Zod schema for OAuth configuration validation.\n *\n * @remarks\n * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field\n * should contain the private key in JWK (JSON Web Key) format as a string.\n */\nexport const OAuthConfigSchema = z.object({\n  /**\n   * URL to the OAuth client metadata JSON document.\n   * This document describes your application to the authorization server.\n   *\n   * @see https://atproto.com/specs/oauth#client-metadata\n   */\n  clientId: z.string().url(),\n\n  /**\n   * URL where users are redirected after authentication.\n   * Must match one of the redirect URIs in your client metadata.\n   */\n  redirectUri: z.string().url(),\n\n  /**\n   * OAuth scopes to request, space-separated.\n   *\n   * Can be a string of space-separated permissions or use the permission system:\n   *\n   * @example Using presets\n   * ```typescript\n   * import { ScopePresets } from '@hypercerts-org/sdk-core';\n   * scope: ScopePresets.EMAIL_AND_PROFILE\n   * ```\n   *\n   * @example Building custom scopes\n   * ```typescript\n   * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';\n   * scope: buildScope(\n   *   new PermissionBuilder()\n   *     .accountEmail('read')\n   *     .repoWrite('app.bsky.feed.post')\n   *     .build()\n   * )\n   * ```\n   *\n   * @example Legacy scopes\n   * ```typescript\n   * scope: \"atproto transition:generic\"\n   * ```\n   *\n   * @see https://atproto.com/specs/permission for permission details\n   */\n  scope: z.string().min(1, \"OAuth scope is required\"),\n\n  /**\n   * URL to your public JWKS (JSON Web Key Set) endpoint.\n   * Used by the authorization server to verify your client's signatures.\n   */\n  jwksUri: z.string().url(),\n\n  /**\n   * Private JWK (JSON Web Key) as a JSON string.\n   * Used for signing DPoP proofs and client assertions.\n   *\n   * @remarks\n   * This should be kept secret and never exposed to clients.\n   * Typically loaded from environment variables or a secrets manager.\n   */\n  jwkPrivate: z.string(),\n});\n\n/**\n * Zod schema for server URL configuration.\n *\n * @remarks\n * At least one server (PDS or SDS) should be configured for the SDK to be useful.\n */\nexport const ServerConfigSchema = z.object({\n  /**\n   * Personal Data Server URL - the user's own AT Protocol server.\n   * This is the primary server for user data operations.\n   *\n   * @example \"https://bsky.social\"\n   */\n  pds: z.string().url().optional(),\n\n  /**\n   * Shared Data Server URL - for collaborative data storage.\n   * Required for collaborator and organization operations.\n   *\n   * @example \"https://sds.hypercerts.org\"\n   */\n  sds: z.string().url().optional(),\n});\n\n/**\n * Zod schema for timeout configuration.\n *\n * @remarks\n * All timeout values are in milliseconds.\n */\nexport const TimeoutConfigSchema = z.object({\n  /**\n   * Timeout for fetching PDS metadata during identity resolution.\n   * @default 5000 (5 seconds, set by OAuthClient)\n   */\n  pdsMetadata: z.number().positive().optional(),\n\n  /**\n   * Timeout for general API requests to PDS/SDS.\n   * @default 30000 (30 seconds)\n   */\n  apiRequests: z.number().positive().optional(),\n});\n\n/**\n * Zod schema for SDK configuration validation.\n *\n * @remarks\n * This schema validates only the primitive/serializable parts of the configuration.\n * Storage interfaces ({@link SessionStore}, {@link StateStore}) cannot be validated\n * with Zod as they are runtime objects.\n */\nexport const ATProtoSDKConfigSchema = z.object({\n  oauth: OAuthConfigSchema,\n  servers: ServerConfigSchema.optional(),\n  timeouts: TimeoutConfigSchema.optional(),\n});\n\n/**\n * Configuration options for the ATProto SDK.\n *\n * This interface defines all configuration needed to initialize the SDK,\n * including OAuth credentials, server endpoints, and optional customizations.\n *\n * @example Minimal configuration\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: {\n *     clientId: \"https://my-app.com/client-metadata.json\",\n *     redirectUri: \"https://my-app.com/callback\",\n *     scope: \"atproto transition:generic\",\n *     jwksUri: \"https://my-app.com/.well-known/jwks.json\",\n *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,\n *   },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *   },\n * };\n * ```\n *\n * @example Full configuration with custom storage\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: { ... },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *     sds: \"https://sds.hypercerts.org\",\n *   },\n *   storage: {\n *     sessionStore: new RedisSessionStore(redisClient),\n *     stateStore: new RedisStateStore(redisClient),\n *   },\n *   timeouts: {\n *     pdsMetadata: 5000,\n *     apiRequests: 30000,\n *   },\n *   logger: console,\n * };\n * ```\n */\nexport interface ATProtoSDKConfig {\n  /**\n   * OAuth 2.0 configuration for authentication.\n   *\n   * Required fields for the OAuth flow with DPoP (Demonstrating Proof of Possession).\n   * Your application must host the client metadata and JWKS endpoints.\n   *\n   * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification\n   */\n  oauth: z.infer<typeof OAuthConfigSchema>;\n\n  /**\n   * Server URLs for PDS and SDS connections.\n   *\n   * - **PDS**: Personal Data Server - user's own data storage\n   * - **SDS**: Shared Data Server - collaborative storage with access control\n   */\n  servers?: z.infer<typeof ServerConfigSchema>;\n\n  /**\n   * Storage adapters for persisting OAuth sessions and state.\n   *\n   * If not provided, in-memory implementations are used automatically.\n   * **Warning**: In-memory storage is lost on process restart - use persistent\n   * storage (Redis, database, etc.) in production.\n   *\n   * @example\n   * ```typescript\n   * storage: {\n   *   sessionStore: new RedisSessionStore(redis),\n   *   stateStore: new RedisStateStore(redis),\n   * }\n   * ```\n   */\n  storage?: {\n    /**\n     * Persistent storage for OAuth sessions.\n     * Sessions contain access tokens, refresh tokens, and DPoP keys.\n     */\n    sessionStore?: SessionStore;\n\n    /**\n     * Temporary storage for OAuth state during the authorization flow.\n     * State is short-lived and used for PKCE and CSRF protection.\n     */\n    stateStore?: StateStore;\n  };\n\n  /**\n   * Custom fetch implementation for HTTP requests.\n   *\n   * Use this to add custom headers, logging, or to use a different HTTP client.\n   * Must be compatible with the standard Fetch API.\n   *\n   * @example\n   * ```typescript\n   * fetch: async (url, init) => {\n   *   console.log(`Fetching: ${url}`);\n   *   return globalThis.fetch(url, init);\n   * }\n   * ```\n   */\n  fetch?: typeof fetch;\n\n  /**\n   * Timeout configuration for network requests.\n   * Values are in milliseconds.\n   */\n  timeouts?: z.infer<typeof TimeoutConfigSchema>;\n\n  /**\n   * Cache for profiles, metadata, and other frequently accessed data.\n   *\n   * Implementing caching can significantly reduce API calls and improve performance.\n   * The SDK does not provide a default cache - you must implement {@link CacheInterface}.\n   */\n  cache?: CacheInterface;\n\n  /**\n   * Logger for debugging and observability.\n   *\n   * The logger receives debug, info, warn, and error messages from the SDK.\n   * Compatible with `console` or any logger implementing {@link LoggerInterface}.\n   *\n   * @example\n   * ```typescript\n   * logger: console\n   * // or\n   * logger: pino()\n   * // or\n   * logger: winston.createLogger({ ... })\n   * ```\n   */\n  logger?: LoggerInterface;\n}\n","import type { OAuthSession } from \"@atproto/oauth-client-node\";\nimport { z } from \"zod\";\n\n/**\n * Decentralized Identifier (DID) - a unique, persistent identifier for AT Protocol users.\n *\n * DIDs are the canonical identifier for users in the AT Protocol ecosystem.\n * Unlike handles which can change, DIDs remain constant for the lifetime of an account.\n *\n * @remarks\n * AT Protocol supports multiple DID methods:\n * - `did:plc:` - PLC (Public Ledger of Credentials) DIDs, most common for Bluesky users\n * - `did:web:` - Web DIDs, resolved via HTTPS\n *\n * @example\n * ```typescript\n * const did: DID = \"did:plc:ewvi7nxzyoun6zhxrhs64oiz\";\n * const webDid: DID = \"did:web:example.com\";\n * ```\n *\n * @see https://atproto.com/specs/did for DID specification\n */\nexport type DID = string;\n\n/**\n * OAuth session with DPoP (Demonstrating Proof of Possession) support.\n *\n * This type represents an authenticated user session. It wraps the\n * `@atproto/oauth-client-node` OAuthSession and contains:\n * - Access token for API requests\n * - Refresh token for obtaining new access tokens\n * - DPoP key pair for proof-of-possession\n * - User's DID and other identity information\n *\n * @remarks\n * Sessions are managed by the SDK and automatically refresh when tokens expire.\n * Store the user's DID to restore sessions later with {@link ATProtoSDK.restoreSession}.\n *\n * Key properties from OAuthSession:\n * - `did` or `sub`: The user's DID\n * - `handle`: The user's handle (e.g., \"user.bsky.social\")\n *\n * @example\n * ```typescript\n * const session = await sdk.callback(params);\n *\n * // Access user identity\n * console.log(`Logged in as: ${session.did}`);\n *\n * // Use session for repository operations\n * const repo = sdk.repository(session);\n * ```\n *\n * @see https://atproto.com/specs/oauth for OAuth specification\n */\nexport type Session = OAuthSession;\n\n/**\n * Zod schema for collaborator permissions in SDS repositories.\n *\n * Defines the granular permissions a collaborator can have on a shared repository.\n * Permissions follow a hierarchical model where higher-level permissions\n * typically imply lower-level ones.\n */\nexport const CollaboratorPermissionsSchema = z.object({\n  /**\n   * Can read/view records in the repository.\n   * This is the most basic permission level.\n   */\n  read: z.boolean(),\n\n  /**\n   * Can create new records in the repository.\n   * Typically implies `read` permission.\n   */\n  create: z.boolean(),\n\n  /**\n   * Can modify existing records in the repository.\n   * Typically implies `read` and `create` permissions.\n   */\n  update: z.boolean(),\n\n  /**\n   * Can delete records from the repository.\n   * Typically implies `read`, `create`, and `update` permissions.\n   */\n  delete: z.boolean(),\n\n  /**\n   * Can manage collaborators and their permissions.\n   * Administrative permission that allows inviting/removing collaborators.\n   */\n  admin: z.boolean(),\n\n  /**\n   * Full ownership of the repository.\n   * Owners have all permissions and cannot be removed by other admins.\n   * There must always be at least one owner.\n   */\n  owner: z.boolean(),\n});\n\n/**\n * Collaborator permissions for SDS (Shared Data Server) repositories.\n *\n * These permissions control what actions a collaborator can perform\n * on records within a shared repository.\n *\n * @example\n * ```typescript\n * // Read-only collaborator\n * const readOnlyPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: false,\n *   update: false,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Editor collaborator\n * const editorPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Admin collaborator\n * const adminPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: true,\n *   admin: true,\n *   owner: false,\n * };\n * ```\n */\nexport type CollaboratorPermissions = z.infer<typeof CollaboratorPermissionsSchema>;\n\n/**\n * Zod schema for SDS organization data.\n *\n * Organizations are top-level entities in SDS that can own repositories\n * and have multiple collaborators with different permission levels.\n */\nexport const OrganizationSchema = z.object({\n  /**\n   * The organization's DID - unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  did: z.string(),\n\n  /**\n   * The organization's handle - human-readable identifier.\n   * Format: \"orgname.sds.hypercerts.org\" or similar\n   */\n  handle: z.string(),\n\n  /**\n   * Display name for the organization.\n   */\n  name: z.string(),\n\n  /**\n   * Optional description of the organization's purpose.\n   */\n  description: z.string().optional(),\n\n  /**\n   * ISO 8601 timestamp when the organization was created.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  createdAt: z.string(),\n\n  /**\n   * The current user's permissions within this organization.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * How the current user relates to this organization.\n   * - `\"owner\"`: User created or owns the organization\n   * - `\"shared\"`: User was invited to collaborate (has permissions)\n   * - `\"none\"`: User has no access to this organization\n   */\n  accessType: z.enum([\"owner\", \"shared\", \"none\"]),\n});\n\n/**\n * SDS Organization entity.\n *\n * Represents an organization on a Shared Data Server. Organizations\n * provide a way to group repositories and manage access for teams.\n *\n * @example\n * ```typescript\n * const org: Organization = {\n *   did: \"did:plc:org123abc\",\n *   handle: \"my-team.sds.hypercerts.org\",\n *   name: \"My Team\",\n *   description: \"A team working on impact certificates\",\n *   createdAt: \"2024-01-15T10:30:00.000Z\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: true,\n *     admin: true,\n *     owner: true,\n *   },\n *   accessType: \"owner\",\n * };\n * ```\n */\nexport type Organization = z.infer<typeof OrganizationSchema>;\n\n/**\n * Zod schema for collaborator data.\n *\n * Represents a user who has been granted access to a shared repository\n * or organization with specific permissions.\n */\nexport const CollaboratorSchema = z.object({\n  /**\n   * The collaborator's DID - their unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  userDid: z.string(),\n\n  /**\n   * The permissions granted to this collaborator.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * DID of the user who granted these permissions.\n   * Useful for audit trails.\n   */\n  grantedBy: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were granted.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  grantedAt: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were revoked, if applicable.\n   * Undefined if the collaborator is still active.\n   */\n  revokedAt: z.string().optional(),\n});\n\n/**\n * Collaborator information for SDS repositories.\n *\n * Represents a user who has been granted access to collaborate on\n * a shared repository or organization.\n *\n * @example\n * ```typescript\n * const collaborator: Collaborator = {\n *   userDid: \"did:plc:user456def\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: false,\n *     admin: false,\n *     owner: false,\n *   },\n *   grantedBy: \"did:plc:owner123abc\",\n *   grantedAt: \"2024-02-01T14:00:00.000Z\",\n * };\n * ```\n */\nexport type Collaborator = z.infer<typeof CollaboratorSchema>;\n"],"names":["z"],"mappings":"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"}

package/dist/types.d.ts

@@ -755,7 +755,32 @@ declare const OAuthConfigSchema: z.ZodObject<{
     redirectUri: z.ZodString;
     /**
      * OAuth scopes to request, space-separated.
-     * Common scopes: "atproto", "transition:generic"
+     *
+     * Can be a string of space-separated permissions or use the permission system:
+     *
+     * @example Using presets
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     * scope: ScopePresets.EMAIL_AND_PROFILE
+     * ```
+     *
+     * @example Building custom scopes
+     * ```typescript
+     * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+     * scope: buildScope(
+     *   new PermissionBuilder()
+     *     .accountEmail('read')
+     *     .repoWrite('app.bsky.feed.post')
+     *     .build()
+     * )
+     * ```
+     *
+     * @example Legacy scopes
+     * ```typescript
+     * scope: "atproto transition:generic"
+     * ```
+     *
+     * @see https://atproto.com/specs/permission for permission details
      */
     scope: z.ZodString;
     /**
@@ -861,7 +886,32 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
         redirectUri: z.ZodString;
         /**
          * OAuth scopes to request, space-separated.
-         * Common scopes: "atproto", "transition:generic"
+         *
+         * Can be a string of space-separated permissions or use the permission system:
+         *
+         * @example Using presets
+         * ```typescript
+         * import { ScopePresets } from '@hypercerts-org/sdk-core';
+         * scope: ScopePresets.EMAIL_AND_PROFILE
+         * ```
+         *
+         * @example Building custom scopes
+         * ```typescript
+         * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+         * scope: buildScope(
+         *   new PermissionBuilder()
+         *     .accountEmail('read')
+         *     .repoWrite('app.bsky.feed.post')
+         *     .build()
+         * )
+         * ```
+         *
+         * @example Legacy scopes
+         * ```typescript
+         * scope: "atproto transition:generic"
+         * ```
+         *
+         * @see https://atproto.com/specs/permission for permission details
          */
         scope: z.ZodString;
         /**
@@ -2145,13 +2195,47 @@ interface AuthorizeOptions {
      * OAuth scope string to request specific permissions.
      * Overrides the default scope configured in {@link ATProtoSDKConfig.oauth.scope}.
      *
-     * @example
+     * Can use the permission system for type-safe scope building.
+     *
+     * @example Using presets
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     *
+     * // Request email and profile access
+     * await sdk.authorize("user.bsky.social", {
+     *   scope: ScopePresets.EMAIL_AND_PROFILE
+     * });
+     *
+     * // Request full posting capabilities
+     * await sdk.authorize("user.bsky.social", {
+     *   scope: ScopePresets.POSTING_APP
+     * });
+     * ```
+     *
+     * @example Building custom scopes
+     * ```typescript
+     * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+     *
+     * const scope = buildScope(
+     *   new PermissionBuilder()
+     *     .accountEmail('read')
+     *     .repoWrite('app.bsky.feed.post')
+     *     .blob(['image/*'])
+     *     .build()
+     * );
+     *
+     * await sdk.authorize("user.bsky.social", { scope });
+     * ```
+     *
+     * @example Legacy scopes
      * ```typescript
      * // Request read-only access
      * await sdk.authorize("user.bsky.social", { scope: "atproto" });
      *
-     * // Request full access (default typically includes transition:generic)
-     * await sdk.authorize("user.bsky.social", { scope: "atproto transition:generic" });
+     * // Request full access (legacy)
+     * await sdk.authorize("user.bsky.social", {
+     *   scope: "atproto transition:generic"
+     * });
      * ```
      */
     scope?: string;

package/dist/types.mjs

@@ -22,9 +22,34 @@ const OAuthConfigSchema = z.object({
     redirectUri: z.string().url(),
     /**
      * OAuth scopes to request, space-separated.
-     * Common scopes: "atproto", "transition:generic"
+     *
+     * Can be a string of space-separated permissions or use the permission system:
+     *
+     * @example Using presets
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     * scope: ScopePresets.EMAIL_AND_PROFILE
+     * ```
+     *
+     * @example Building custom scopes
+     * ```typescript
+     * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+     * scope: buildScope(
+     *   new PermissionBuilder()
+     *     .accountEmail('read')
+     *     .repoWrite('app.bsky.feed.post')
+     *     .build()
+     * )
+     * ```
+     *
+     * @example Legacy scopes
+     * ```typescript
+     * scope: "atproto transition:generic"
+     * ```
+     *
+     * @see https://atproto.com/specs/permission for permission details
      */
-    scope: z.string(),
+    scope: z.string().min(1, "OAuth scope is required"),
     /**
      * URL to your public JWKS (JSON Web Key Set) endpoint.
      * Used by the authorization server to verify your client's signatures.

package/dist/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","sources":["../src/core/config.ts","../src/core/types.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { SessionStore, StateStore, CacheInterface, LoggerInterface } from \"./interfaces.js\";\n\n/**\n * Zod schema for OAuth configuration validation.\n *\n * @remarks\n * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field\n * should contain the private key in JWK (JSON Web Key) format as a string.\n */\nexport const OAuthConfigSchema = z.object({\n  /**\n   * URL to the OAuth client metadata JSON document.\n   * This document describes your application to the authorization server.\n   *\n   * @see https://atproto.com/specs/oauth#client-metadata\n   */\n  clientId: z.string().url(),\n\n  /**\n   * URL where users are redirected after authentication.\n   * Must match one of the redirect URIs in your client metadata.\n   */\n  redirectUri: z.string().url(),\n\n  /**\n   * OAuth scopes to request, space-separated.\n   * Common scopes: \"atproto\", \"transition:generic\"\n   */\n  scope: z.string(),\n\n  /**\n   * URL to your public JWKS (JSON Web Key Set) endpoint.\n   * Used by the authorization server to verify your client's signatures.\n   */\n  jwksUri: z.string().url(),\n\n  /**\n   * Private JWK (JSON Web Key) as a JSON string.\n   * Used for signing DPoP proofs and client assertions.\n   *\n   * @remarks\n   * This should be kept secret and never exposed to clients.\n   * Typically loaded from environment variables or a secrets manager.\n   */\n  jwkPrivate: z.string(),\n});\n\n/**\n * Zod schema for server URL configuration.\n *\n * @remarks\n * At least one server (PDS or SDS) should be configured for the SDK to be useful.\n */\nexport const ServerConfigSchema = z.object({\n  /**\n   * Personal Data Server URL - the user's own AT Protocol server.\n   * This is the primary server for user data operations.\n   *\n   * @example \"https://bsky.social\"\n   */\n  pds: z.string().url().optional(),\n\n  /**\n   * Shared Data Server URL - for collaborative data storage.\n   * Required for collaborator and organization operations.\n   *\n   * @example \"https://sds.hypercerts.org\"\n   */\n  sds: z.string().url().optional(),\n});\n\n/**\n * Zod schema for timeout configuration.\n *\n * @remarks\n * All timeout values are in milliseconds.\n */\nexport const TimeoutConfigSchema = z.object({\n  /**\n   * Timeout for fetching PDS metadata during identity resolution.\n   * @default 5000 (5 seconds, set by OAuthClient)\n   */\n  pdsMetadata: z.number().positive().optional(),\n\n  /**\n   * Timeout for general API requests to PDS/SDS.\n   * @default 30000 (30 seconds)\n   */\n  apiRequests: z.number().positive().optional(),\n});\n\n/**\n * Zod schema for SDK configuration validation.\n *\n * @remarks\n * This schema validates only the primitive/serializable parts of the configuration.\n * Storage interfaces ({@link SessionStore}, {@link StateStore}) cannot be validated\n * with Zod as they are runtime objects.\n */\nexport const ATProtoSDKConfigSchema = z.object({\n  oauth: OAuthConfigSchema,\n  servers: ServerConfigSchema.optional(),\n  timeouts: TimeoutConfigSchema.optional(),\n});\n\n/**\n * Configuration options for the ATProto SDK.\n *\n * This interface defines all configuration needed to initialize the SDK,\n * including OAuth credentials, server endpoints, and optional customizations.\n *\n * @example Minimal configuration\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: {\n *     clientId: \"https://my-app.com/client-metadata.json\",\n *     redirectUri: \"https://my-app.com/callback\",\n *     scope: \"atproto transition:generic\",\n *     jwksUri: \"https://my-app.com/.well-known/jwks.json\",\n *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,\n *   },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *   },\n * };\n * ```\n *\n * @example Full configuration with custom storage\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: { ... },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *     sds: \"https://sds.hypercerts.org\",\n *   },\n *   storage: {\n *     sessionStore: new RedisSessionStore(redisClient),\n *     stateStore: new RedisStateStore(redisClient),\n *   },\n *   timeouts: {\n *     pdsMetadata: 5000,\n *     apiRequests: 30000,\n *   },\n *   logger: console,\n * };\n * ```\n */\nexport interface ATProtoSDKConfig {\n  /**\n   * OAuth 2.0 configuration for authentication.\n   *\n   * Required fields for the OAuth flow with DPoP (Demonstrating Proof of Possession).\n   * Your application must host the client metadata and JWKS endpoints.\n   *\n   * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification\n   */\n  oauth: z.infer<typeof OAuthConfigSchema>;\n\n  /**\n   * Server URLs for PDS and SDS connections.\n   *\n   * - **PDS**: Personal Data Server - user's own data storage\n   * - **SDS**: Shared Data Server - collaborative storage with access control\n   */\n  servers?: z.infer<typeof ServerConfigSchema>;\n\n  /**\n   * Storage adapters for persisting OAuth sessions and state.\n   *\n   * If not provided, in-memory implementations are used automatically.\n   * **Warning**: In-memory storage is lost on process restart - use persistent\n   * storage (Redis, database, etc.) in production.\n   *\n   * @example\n   * ```typescript\n   * storage: {\n   *   sessionStore: new RedisSessionStore(redis),\n   *   stateStore: new RedisStateStore(redis),\n   * }\n   * ```\n   */\n  storage?: {\n    /**\n     * Persistent storage for OAuth sessions.\n     * Sessions contain access tokens, refresh tokens, and DPoP keys.\n     */\n    sessionStore?: SessionStore;\n\n    /**\n     * Temporary storage for OAuth state during the authorization flow.\n     * State is short-lived and used for PKCE and CSRF protection.\n     */\n    stateStore?: StateStore;\n  };\n\n  /**\n   * Custom fetch implementation for HTTP requests.\n   *\n   * Use this to add custom headers, logging, or to use a different HTTP client.\n   * Must be compatible with the standard Fetch API.\n   *\n   * @example\n   * ```typescript\n   * fetch: async (url, init) => {\n   *   console.log(`Fetching: ${url}`);\n   *   return globalThis.fetch(url, init);\n   * }\n   * ```\n   */\n  fetch?: typeof fetch;\n\n  /**\n   * Timeout configuration for network requests.\n   * Values are in milliseconds.\n   */\n  timeouts?: z.infer<typeof TimeoutConfigSchema>;\n\n  /**\n   * Cache for profiles, metadata, and other frequently accessed data.\n   *\n   * Implementing caching can significantly reduce API calls and improve performance.\n   * The SDK does not provide a default cache - you must implement {@link CacheInterface}.\n   */\n  cache?: CacheInterface;\n\n  /**\n   * Logger for debugging and observability.\n   *\n   * The logger receives debug, info, warn, and error messages from the SDK.\n   * Compatible with `console` or any logger implementing {@link LoggerInterface}.\n   *\n   * @example\n   * ```typescript\n   * logger: console\n   * // or\n   * logger: pino()\n   * // or\n   * logger: winston.createLogger({ ... })\n   * ```\n   */\n  logger?: LoggerInterface;\n}\n","import type { OAuthSession } from \"@atproto/oauth-client-node\";\nimport { z } from \"zod\";\n\n/**\n * Decentralized Identifier (DID) - a unique, persistent identifier for AT Protocol users.\n *\n * DIDs are the canonical identifier for users in the AT Protocol ecosystem.\n * Unlike handles which can change, DIDs remain constant for the lifetime of an account.\n *\n * @remarks\n * AT Protocol supports multiple DID methods:\n * - `did:plc:` - PLC (Public Ledger of Credentials) DIDs, most common for Bluesky users\n * - `did:web:` - Web DIDs, resolved via HTTPS\n *\n * @example\n * ```typescript\n * const did: DID = \"did:plc:ewvi7nxzyoun6zhxrhs64oiz\";\n * const webDid: DID = \"did:web:example.com\";\n * ```\n *\n * @see https://atproto.com/specs/did for DID specification\n */\nexport type DID = string;\n\n/**\n * OAuth session with DPoP (Demonstrating Proof of Possession) support.\n *\n * This type represents an authenticated user session. It wraps the\n * `@atproto/oauth-client-node` OAuthSession and contains:\n * - Access token for API requests\n * - Refresh token for obtaining new access tokens\n * - DPoP key pair for proof-of-possession\n * - User's DID and other identity information\n *\n * @remarks\n * Sessions are managed by the SDK and automatically refresh when tokens expire.\n * Store the user's DID to restore sessions later with {@link ATProtoSDK.restoreSession}.\n *\n * Key properties from OAuthSession:\n * - `did` or `sub`: The user's DID\n * - `handle`: The user's handle (e.g., \"user.bsky.social\")\n *\n * @example\n * ```typescript\n * const session = await sdk.callback(params);\n *\n * // Access user identity\n * console.log(`Logged in as: ${session.did}`);\n *\n * // Use session for repository operations\n * const repo = sdk.repository(session);\n * ```\n *\n * @see https://atproto.com/specs/oauth for OAuth specification\n */\nexport type Session = OAuthSession;\n\n/**\n * Zod schema for collaborator permissions in SDS repositories.\n *\n * Defines the granular permissions a collaborator can have on a shared repository.\n * Permissions follow a hierarchical model where higher-level permissions\n * typically imply lower-level ones.\n */\nexport const CollaboratorPermissionsSchema = z.object({\n  /**\n   * Can read/view records in the repository.\n   * This is the most basic permission level.\n   */\n  read: z.boolean(),\n\n  /**\n   * Can create new records in the repository.\n   * Typically implies `read` permission.\n   */\n  create: z.boolean(),\n\n  /**\n   * Can modify existing records in the repository.\n   * Typically implies `read` and `create` permissions.\n   */\n  update: z.boolean(),\n\n  /**\n   * Can delete records from the repository.\n   * Typically implies `read`, `create`, and `update` permissions.\n   */\n  delete: z.boolean(),\n\n  /**\n   * Can manage collaborators and their permissions.\n   * Administrative permission that allows inviting/removing collaborators.\n   */\n  admin: z.boolean(),\n\n  /**\n   * Full ownership of the repository.\n   * Owners have all permissions and cannot be removed by other admins.\n   * There must always be at least one owner.\n   */\n  owner: z.boolean(),\n});\n\n/**\n * Collaborator permissions for SDS (Shared Data Server) repositories.\n *\n * These permissions control what actions a collaborator can perform\n * on records within a shared repository.\n *\n * @example\n * ```typescript\n * // Read-only collaborator\n * const readOnlyPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: false,\n *   update: false,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Editor collaborator\n * const editorPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Admin collaborator\n * const adminPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: true,\n *   admin: true,\n *   owner: false,\n * };\n * ```\n */\nexport type CollaboratorPermissions = z.infer<typeof CollaboratorPermissionsSchema>;\n\n/**\n * Zod schema for SDS organization data.\n *\n * Organizations are top-level entities in SDS that can own repositories\n * and have multiple collaborators with different permission levels.\n */\nexport const OrganizationSchema = z.object({\n  /**\n   * The organization's DID - unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  did: z.string(),\n\n  /**\n   * The organization's handle - human-readable identifier.\n   * Format: \"orgname.sds.hypercerts.org\" or similar\n   */\n  handle: z.string(),\n\n  /**\n   * Display name for the organization.\n   */\n  name: z.string(),\n\n  /**\n   * Optional description of the organization's purpose.\n   */\n  description: z.string().optional(),\n\n  /**\n   * ISO 8601 timestamp when the organization was created.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  createdAt: z.string(),\n\n  /**\n   * The current user's permissions within this organization.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * How the current user relates to this organization.\n   * - `\"owner\"`: User created or owns the organization\n   * - `\"shared\"`: User was invited to collaborate (has permissions)\n   * - `\"none\"`: User has no access to this organization\n   */\n  accessType: z.enum([\"owner\", \"shared\", \"none\"]),\n});\n\n/**\n * SDS Organization entity.\n *\n * Represents an organization on a Shared Data Server. Organizations\n * provide a way to group repositories and manage access for teams.\n *\n * @example\n * ```typescript\n * const org: Organization = {\n *   did: \"did:plc:org123abc\",\n *   handle: \"my-team.sds.hypercerts.org\",\n *   name: \"My Team\",\n *   description: \"A team working on impact certificates\",\n *   createdAt: \"2024-01-15T10:30:00.000Z\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: true,\n *     admin: true,\n *     owner: true,\n *   },\n *   accessType: \"owner\",\n * };\n * ```\n */\nexport type Organization = z.infer<typeof OrganizationSchema>;\n\n/**\n * Zod schema for collaborator data.\n *\n * Represents a user who has been granted access to a shared repository\n * or organization with specific permissions.\n */\nexport const CollaboratorSchema = z.object({\n  /**\n   * The collaborator's DID - their unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  userDid: z.string(),\n\n  /**\n   * The permissions granted to this collaborator.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * DID of the user who granted these permissions.\n   * Useful for audit trails.\n   */\n  grantedBy: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were granted.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  grantedAt: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were revoked, if applicable.\n   * Undefined if the collaborator is still active.\n   */\n  revokedAt: z.string().optional(),\n});\n\n/**\n * Collaborator information for SDS repositories.\n *\n * Represents a user who has been granted access to collaborate on\n * a shared repository or organization.\n *\n * @example\n * ```typescript\n * const collaborator: Collaborator = {\n *   userDid: \"did:plc:user456def\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: false,\n *     admin: false,\n *     owner: false,\n *   },\n *   grantedBy: \"did:plc:owner123abc\",\n *   grantedAt: \"2024-02-01T14:00:00.000Z\",\n * };\n * ```\n */\nexport type Collaborator = z.infer<typeof CollaboratorSchema>;\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.mjs","sources":["../src/core/config.ts","../src/core/types.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { SessionStore, StateStore, CacheInterface, LoggerInterface } from \"./interfaces.js\";\n\n/**\n * Zod schema for OAuth configuration validation.\n *\n * @remarks\n * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field\n * should contain the private key in JWK (JSON Web Key) format as a string.\n */\nexport const OAuthConfigSchema = z.object({\n  /**\n   * URL to the OAuth client metadata JSON document.\n   * This document describes your application to the authorization server.\n   *\n   * @see https://atproto.com/specs/oauth#client-metadata\n   */\n  clientId: z.string().url(),\n\n  /**\n   * URL where users are redirected after authentication.\n   * Must match one of the redirect URIs in your client metadata.\n   */\n  redirectUri: z.string().url(),\n\n  /**\n   * OAuth scopes to request, space-separated.\n   *\n   * Can be a string of space-separated permissions or use the permission system:\n   *\n   * @example Using presets\n   * ```typescript\n   * import { ScopePresets } from '@hypercerts-org/sdk-core';\n   * scope: ScopePresets.EMAIL_AND_PROFILE\n   * ```\n   *\n   * @example Building custom scopes\n   * ```typescript\n   * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';\n   * scope: buildScope(\n   *   new PermissionBuilder()\n   *     .accountEmail('read')\n   *     .repoWrite('app.bsky.feed.post')\n   *     .build()\n   * )\n   * ```\n   *\n   * @example Legacy scopes\n   * ```typescript\n   * scope: \"atproto transition:generic\"\n   * ```\n   *\n   * @see https://atproto.com/specs/permission for permission details\n   */\n  scope: z.string().min(1, \"OAuth scope is required\"),\n\n  /**\n   * URL to your public JWKS (JSON Web Key Set) endpoint.\n   * Used by the authorization server to verify your client's signatures.\n   */\n  jwksUri: z.string().url(),\n\n  /**\n   * Private JWK (JSON Web Key) as a JSON string.\n   * Used for signing DPoP proofs and client assertions.\n   *\n   * @remarks\n   * This should be kept secret and never exposed to clients.\n   * Typically loaded from environment variables or a secrets manager.\n   */\n  jwkPrivate: z.string(),\n});\n\n/**\n * Zod schema for server URL configuration.\n *\n * @remarks\n * At least one server (PDS or SDS) should be configured for the SDK to be useful.\n */\nexport const ServerConfigSchema = z.object({\n  /**\n   * Personal Data Server URL - the user's own AT Protocol server.\n   * This is the primary server for user data operations.\n   *\n   * @example \"https://bsky.social\"\n   */\n  pds: z.string().url().optional(),\n\n  /**\n   * Shared Data Server URL - for collaborative data storage.\n   * Required for collaborator and organization operations.\n   *\n   * @example \"https://sds.hypercerts.org\"\n   */\n  sds: z.string().url().optional(),\n});\n\n/**\n * Zod schema for timeout configuration.\n *\n * @remarks\n * All timeout values are in milliseconds.\n */\nexport const TimeoutConfigSchema = z.object({\n  /**\n   * Timeout for fetching PDS metadata during identity resolution.\n   * @default 5000 (5 seconds, set by OAuthClient)\n   */\n  pdsMetadata: z.number().positive().optional(),\n\n  /**\n   * Timeout for general API requests to PDS/SDS.\n   * @default 30000 (30 seconds)\n   */\n  apiRequests: z.number().positive().optional(),\n});\n\n/**\n * Zod schema for SDK configuration validation.\n *\n * @remarks\n * This schema validates only the primitive/serializable parts of the configuration.\n * Storage interfaces ({@link SessionStore}, {@link StateStore}) cannot be validated\n * with Zod as they are runtime objects.\n */\nexport const ATProtoSDKConfigSchema = z.object({\n  oauth: OAuthConfigSchema,\n  servers: ServerConfigSchema.optional(),\n  timeouts: TimeoutConfigSchema.optional(),\n});\n\n/**\n * Configuration options for the ATProto SDK.\n *\n * This interface defines all configuration needed to initialize the SDK,\n * including OAuth credentials, server endpoints, and optional customizations.\n *\n * @example Minimal configuration\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: {\n *     clientId: \"https://my-app.com/client-metadata.json\",\n *     redirectUri: \"https://my-app.com/callback\",\n *     scope: \"atproto transition:generic\",\n *     jwksUri: \"https://my-app.com/.well-known/jwks.json\",\n *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,\n *   },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *   },\n * };\n * ```\n *\n * @example Full configuration with custom storage\n * ```typescript\n * const config: ATProtoSDKConfig = {\n *   oauth: { ... },\n *   servers: {\n *     pds: \"https://bsky.social\",\n *     sds: \"https://sds.hypercerts.org\",\n *   },\n *   storage: {\n *     sessionStore: new RedisSessionStore(redisClient),\n *     stateStore: new RedisStateStore(redisClient),\n *   },\n *   timeouts: {\n *     pdsMetadata: 5000,\n *     apiRequests: 30000,\n *   },\n *   logger: console,\n * };\n * ```\n */\nexport interface ATProtoSDKConfig {\n  /**\n   * OAuth 2.0 configuration for authentication.\n   *\n   * Required fields for the OAuth flow with DPoP (Demonstrating Proof of Possession).\n   * Your application must host the client metadata and JWKS endpoints.\n   *\n   * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification\n   */\n  oauth: z.infer<typeof OAuthConfigSchema>;\n\n  /**\n   * Server URLs for PDS and SDS connections.\n   *\n   * - **PDS**: Personal Data Server - user's own data storage\n   * - **SDS**: Shared Data Server - collaborative storage with access control\n   */\n  servers?: z.infer<typeof ServerConfigSchema>;\n\n  /**\n   * Storage adapters for persisting OAuth sessions and state.\n   *\n   * If not provided, in-memory implementations are used automatically.\n   * **Warning**: In-memory storage is lost on process restart - use persistent\n   * storage (Redis, database, etc.) in production.\n   *\n   * @example\n   * ```typescript\n   * storage: {\n   *   sessionStore: new RedisSessionStore(redis),\n   *   stateStore: new RedisStateStore(redis),\n   * }\n   * ```\n   */\n  storage?: {\n    /**\n     * Persistent storage for OAuth sessions.\n     * Sessions contain access tokens, refresh tokens, and DPoP keys.\n     */\n    sessionStore?: SessionStore;\n\n    /**\n     * Temporary storage for OAuth state during the authorization flow.\n     * State is short-lived and used for PKCE and CSRF protection.\n     */\n    stateStore?: StateStore;\n  };\n\n  /**\n   * Custom fetch implementation for HTTP requests.\n   *\n   * Use this to add custom headers, logging, or to use a different HTTP client.\n   * Must be compatible with the standard Fetch API.\n   *\n   * @example\n   * ```typescript\n   * fetch: async (url, init) => {\n   *   console.log(`Fetching: ${url}`);\n   *   return globalThis.fetch(url, init);\n   * }\n   * ```\n   */\n  fetch?: typeof fetch;\n\n  /**\n   * Timeout configuration for network requests.\n   * Values are in milliseconds.\n   */\n  timeouts?: z.infer<typeof TimeoutConfigSchema>;\n\n  /**\n   * Cache for profiles, metadata, and other frequently accessed data.\n   *\n   * Implementing caching can significantly reduce API calls and improve performance.\n   * The SDK does not provide a default cache - you must implement {@link CacheInterface}.\n   */\n  cache?: CacheInterface;\n\n  /**\n   * Logger for debugging and observability.\n   *\n   * The logger receives debug, info, warn, and error messages from the SDK.\n   * Compatible with `console` or any logger implementing {@link LoggerInterface}.\n   *\n   * @example\n   * ```typescript\n   * logger: console\n   * // or\n   * logger: pino()\n   * // or\n   * logger: winston.createLogger({ ... })\n   * ```\n   */\n  logger?: LoggerInterface;\n}\n","import type { OAuthSession } from \"@atproto/oauth-client-node\";\nimport { z } from \"zod\";\n\n/**\n * Decentralized Identifier (DID) - a unique, persistent identifier for AT Protocol users.\n *\n * DIDs are the canonical identifier for users in the AT Protocol ecosystem.\n * Unlike handles which can change, DIDs remain constant for the lifetime of an account.\n *\n * @remarks\n * AT Protocol supports multiple DID methods:\n * - `did:plc:` - PLC (Public Ledger of Credentials) DIDs, most common for Bluesky users\n * - `did:web:` - Web DIDs, resolved via HTTPS\n *\n * @example\n * ```typescript\n * const did: DID = \"did:plc:ewvi7nxzyoun6zhxrhs64oiz\";\n * const webDid: DID = \"did:web:example.com\";\n * ```\n *\n * @see https://atproto.com/specs/did for DID specification\n */\nexport type DID = string;\n\n/**\n * OAuth session with DPoP (Demonstrating Proof of Possession) support.\n *\n * This type represents an authenticated user session. It wraps the\n * `@atproto/oauth-client-node` OAuthSession and contains:\n * - Access token for API requests\n * - Refresh token for obtaining new access tokens\n * - DPoP key pair for proof-of-possession\n * - User's DID and other identity information\n *\n * @remarks\n * Sessions are managed by the SDK and automatically refresh when tokens expire.\n * Store the user's DID to restore sessions later with {@link ATProtoSDK.restoreSession}.\n *\n * Key properties from OAuthSession:\n * - `did` or `sub`: The user's DID\n * - `handle`: The user's handle (e.g., \"user.bsky.social\")\n *\n * @example\n * ```typescript\n * const session = await sdk.callback(params);\n *\n * // Access user identity\n * console.log(`Logged in as: ${session.did}`);\n *\n * // Use session for repository operations\n * const repo = sdk.repository(session);\n * ```\n *\n * @see https://atproto.com/specs/oauth for OAuth specification\n */\nexport type Session = OAuthSession;\n\n/**\n * Zod schema for collaborator permissions in SDS repositories.\n *\n * Defines the granular permissions a collaborator can have on a shared repository.\n * Permissions follow a hierarchical model where higher-level permissions\n * typically imply lower-level ones.\n */\nexport const CollaboratorPermissionsSchema = z.object({\n  /**\n   * Can read/view records in the repository.\n   * This is the most basic permission level.\n   */\n  read: z.boolean(),\n\n  /**\n   * Can create new records in the repository.\n   * Typically implies `read` permission.\n   */\n  create: z.boolean(),\n\n  /**\n   * Can modify existing records in the repository.\n   * Typically implies `read` and `create` permissions.\n   */\n  update: z.boolean(),\n\n  /**\n   * Can delete records from the repository.\n   * Typically implies `read`, `create`, and `update` permissions.\n   */\n  delete: z.boolean(),\n\n  /**\n   * Can manage collaborators and their permissions.\n   * Administrative permission that allows inviting/removing collaborators.\n   */\n  admin: z.boolean(),\n\n  /**\n   * Full ownership of the repository.\n   * Owners have all permissions and cannot be removed by other admins.\n   * There must always be at least one owner.\n   */\n  owner: z.boolean(),\n});\n\n/**\n * Collaborator permissions for SDS (Shared Data Server) repositories.\n *\n * These permissions control what actions a collaborator can perform\n * on records within a shared repository.\n *\n * @example\n * ```typescript\n * // Read-only collaborator\n * const readOnlyPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: false,\n *   update: false,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Editor collaborator\n * const editorPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: false,\n *   admin: false,\n *   owner: false,\n * };\n *\n * // Admin collaborator\n * const adminPerms: CollaboratorPermissions = {\n *   read: true,\n *   create: true,\n *   update: true,\n *   delete: true,\n *   admin: true,\n *   owner: false,\n * };\n * ```\n */\nexport type CollaboratorPermissions = z.infer<typeof CollaboratorPermissionsSchema>;\n\n/**\n * Zod schema for SDS organization data.\n *\n * Organizations are top-level entities in SDS that can own repositories\n * and have multiple collaborators with different permission levels.\n */\nexport const OrganizationSchema = z.object({\n  /**\n   * The organization's DID - unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  did: z.string(),\n\n  /**\n   * The organization's handle - human-readable identifier.\n   * Format: \"orgname.sds.hypercerts.org\" or similar\n   */\n  handle: z.string(),\n\n  /**\n   * Display name for the organization.\n   */\n  name: z.string(),\n\n  /**\n   * Optional description of the organization's purpose.\n   */\n  description: z.string().optional(),\n\n  /**\n   * ISO 8601 timestamp when the organization was created.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  createdAt: z.string(),\n\n  /**\n   * The current user's permissions within this organization.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * How the current user relates to this organization.\n   * - `\"owner\"`: User created or owns the organization\n   * - `\"shared\"`: User was invited to collaborate (has permissions)\n   * - `\"none\"`: User has no access to this organization\n   */\n  accessType: z.enum([\"owner\", \"shared\", \"none\"]),\n});\n\n/**\n * SDS Organization entity.\n *\n * Represents an organization on a Shared Data Server. Organizations\n * provide a way to group repositories and manage access for teams.\n *\n * @example\n * ```typescript\n * const org: Organization = {\n *   did: \"did:plc:org123abc\",\n *   handle: \"my-team.sds.hypercerts.org\",\n *   name: \"My Team\",\n *   description: \"A team working on impact certificates\",\n *   createdAt: \"2024-01-15T10:30:00.000Z\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: true,\n *     admin: true,\n *     owner: true,\n *   },\n *   accessType: \"owner\",\n * };\n * ```\n */\nexport type Organization = z.infer<typeof OrganizationSchema>;\n\n/**\n * Zod schema for collaborator data.\n *\n * Represents a user who has been granted access to a shared repository\n * or organization with specific permissions.\n */\nexport const CollaboratorSchema = z.object({\n  /**\n   * The collaborator's DID - their unique identifier.\n   * Format: \"did:plc:...\" or \"did:web:...\"\n   */\n  userDid: z.string(),\n\n  /**\n   * The permissions granted to this collaborator.\n   */\n  permissions: CollaboratorPermissionsSchema,\n\n  /**\n   * DID of the user who granted these permissions.\n   * Useful for audit trails.\n   */\n  grantedBy: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were granted.\n   * Format: \"2024-01-15T10:30:00.000Z\"\n   */\n  grantedAt: z.string(),\n\n  /**\n   * ISO 8601 timestamp when permissions were revoked, if applicable.\n   * Undefined if the collaborator is still active.\n   */\n  revokedAt: z.string().optional(),\n});\n\n/**\n * Collaborator information for SDS repositories.\n *\n * Represents a user who has been granted access to collaborate on\n * a shared repository or organization.\n *\n * @example\n * ```typescript\n * const collaborator: Collaborator = {\n *   userDid: \"did:plc:user456def\",\n *   permissions: {\n *     read: true,\n *     create: true,\n *     update: true,\n *     delete: false,\n *     admin: false,\n *     owner: false,\n *   },\n *   grantedBy: \"did:plc:owner123abc\",\n *   grantedAt: \"2024-02-01T14:00:00.000Z\",\n * };\n * ```\n */\nexport type Collaborator = z.infer<typeof CollaboratorSchema>;\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/sdk-core",
-  "version": "0.9.0-beta.0",
+  "version": "0.10.0-beta.0",
   "description": "Framework-agnostic ATProto SDK core for authentication, repository operations, and lexicon management",
   "main": "dist/index.cjs",
   "repository": {