@hypercerts-org/sdk-core 0.2.0-beta.0 → 0.5.0-beta.0

package/dist/types.cjs

@@ -173,9 +173,10 @@ const OrganizationSchema = zod.z.object({
     /**
      * How the current user relates to this organization.
      * - `"owner"`: User created or owns the organization
-     * - `"collaborator"`: User was invited to collaborate
+     * - `"shared"`: User was invited to collaborate (has permissions)
+     * - `"none"`: User has no access to this organization
      */
-    accessType: zod.z.enum(["owner", "collaborator"]),
+    accessType: zod.z.enum(["owner", "shared", "none"]),
 });
 /**
  * Zod schema for collaborator data.

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   * - `\"collaborator\"`: User was invited to collaborate\n   */\n  accessType: z.enum([\"owner\", \"collaborator\"]),\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   * 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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"}

package/dist/types.d.ts

@@ -232,9 +232,10 @@ declare const OrganizationSchema: z.ZodObject<{
     /**
      * How the current user relates to this organization.
      * - `"owner"`: User created or owns the organization
-     * - `"collaborator"`: User was invited to collaborate
+     * - `"shared"`: User was invited to collaborate (has permissions)
+     * - `"none"`: User has no access to this organization
      */
-    accessType: z.ZodEnum<["owner", "collaborator"]>;
+    accessType: z.ZodEnum<["owner", "shared", "none"]>;
 }, "strip", z.ZodTypeAny, {
     did: string;
     handle: string;
@@ -248,7 +249,7 @@ declare const OrganizationSchema: z.ZodObject<{
         admin: boolean;
         owner: boolean;
     };
-    accessType: "owner" | "collaborator";
+    accessType: "owner" | "shared" | "none";
     description?: string | undefined;
 }, {
     did: string;
@@ -263,7 +264,7 @@ declare const OrganizationSchema: z.ZodObject<{
         admin: boolean;
         owner: boolean;
     };
-    accessType: "owner" | "collaborator";
+    accessType: "owner" | "shared" | "none";
     description?: string | undefined;
 }>;
 /**
@@ -1176,7 +1177,7 @@ interface OrganizationInfo {
     name: string;
     description?: string;
     createdAt: string;
-    accessType: "owner" | "collaborator";
+    accessType: "owner" | "shared" | "none";
     permissions: CollaboratorPermissions;
     collaboratorCount?: number;
     profile?: {
@@ -1242,16 +1243,6 @@ interface HypercertWithMetadata {
     record: HypercertClaim;
 }
 
-/**
- * Repository interfaces - Operation contracts for repository functionality.
- *
- * This module defines the interfaces for all repository operations,
- * providing clear contracts for record management, blob handling,
- * profile management, and domain-specific operations.
- *
- * @packageDocumentation
- */
-
 /**
  * Parameters for creating a new hypercert.
  *
@@ -1998,6 +1989,17 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
  * const hasAccess = await repo.collaborators.hasAccess("did:plc:someone");
  * const role = await repo.collaborators.getRole("did:plc:someone");
  *
+ * // Get current user permissions
+ * const permissions = await repo.collaborators.getPermissions();
+ * if (permissions.admin) {
+ *   // Can manage collaborators
+ * }
+ *
+ * // Transfer ownership
+ * await repo.collaborators.transferOwnership({
+ *   newOwnerDid: "did:plc:new-owner",
+ * });
+ *
  * // Revoke access
  * await repo.collaborators.revoke({ userDid: "did:plc:former-user" });
  * ```
@@ -2026,9 +2028,18 @@ interface CollaboratorOperations {
     /**
      * Lists all collaborators on the repository.
      *
-     * @returns Promise resolving to array of access grants
+     * @param params - Optional pagination parameters
+     * @param params.limit - Maximum number of results (1-100, default 50)
+     * @param params.cursor - Pagination cursor from previous response
+     * @returns Promise resolving to collaborators and optional cursor
      */
-    list(): Promise<RepositoryAccessGrant[]>;
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        collaborators: RepositoryAccessGrant[];
+        cursor?: string;
+    }>;
     /**
      * Checks if a user has any access to the repository.
      *
@@ -2043,6 +2054,24 @@ interface CollaboratorOperations {
      * @returns Promise resolving to role, or `null` if no access
      */
     getRole(userDid: string): Promise<RepositoryRole | null>;
+    /**
+     * Gets the current user's permissions for this repository.
+     *
+     * @returns Promise resolving to permission flags
+     */
+    getPermissions(): Promise<CollaboratorPermissions>;
+    /**
+     * Transfers repository ownership to another user.
+     *
+     * **WARNING**: This action is irreversible. The new owner will have
+     * full control of the repository.
+     *
+     * @param params - Transfer parameters
+     * @param params.newOwnerDid - DID of the user to transfer ownership to
+     */
+    transferOwnership(params: {
+        newOwnerDid: string;
+    }): Promise<void>;
 }
 /**
  * Organization operations for SDS organization management.
@@ -2089,9 +2118,18 @@ interface OrganizationOperations {
     /**
      * Lists organizations the current user has access to.
      *
-     * @returns Promise resolving to array of organization info
+     * @param params - Optional pagination parameters
+     * @param params.limit - Maximum number of results (1-100, default 50)
+     * @param params.cursor - Pagination cursor from previous response
+     * @returns Promise resolving to organizations and optional cursor
      */
-    list(): Promise<OrganizationInfo[]>;
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        organizations: OrganizationInfo[];
+        cursor?: string;
+    }>;
 }
 
 /**

package/dist/types.mjs

@@ -171,9 +171,10 @@ const OrganizationSchema = z.object({
     /**
      * How the current user relates to this organization.
      * - `"owner"`: User created or owns the organization
-     * - `"collaborator"`: User was invited to collaborate
+     * - `"shared"`: User was invited to collaborate (has permissions)
+     * - `"none"`: User has no access to this organization
      */
-    accessType: z.enum(["owner", "collaborator"]),
+    accessType: z.enum(["owner", "shared", "none"]),
 });
 /**
  * Zod schema for collaborator data.

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   * - `\"collaborator\"`: User was invited to collaborate\n   */\n  accessType: z.enum([\"owner\", \"collaborator\"]),\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   * 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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/sdk-core",
-  "version": "0.2.0-beta.0",
+  "version": "0.5.0-beta.0",
   "description": "Framework-agnostic ATProto SDK core for authentication, repository operations, and lexicon management",
   "main": "dist/index.cjs",
   "repository": {
@@ -75,7 +75,7 @@
     "@atproto/oauth-client-node": "^0.3.10",
     "eventemitter3": "^5.0.1",
     "zod": "^3.24.4",
-    "@hypercerts-org/lexicon": "0.2.0-beta.0"
+    "@hypercerts-org/lexicon": "0.5.0-beta.0"
   },
   "scripts": {
     "test": "vitest",

package/src/core/types.ts

@@ -185,9 +185,10 @@ export const OrganizationSchema = z.object({
   /**
    * How the current user relates to this organization.
    * - `"owner"`: User created or owns the organization
-   * - `"collaborator"`: User was invited to collaborate
+   * - `"shared"`: User was invited to collaborate (has permissions)
+   * - `"none"`: User has no access to this organization
    */
-  accessType: z.enum(["owner", "collaborator"]),
+  accessType: z.enum(["owner", "shared", "none"]),
 });
 
 /**

package/src/repository/BlobOperationsImpl.ts

@@ -122,7 +122,7 @@ export class BlobOperationsImpl implements BlobOperations {
       }
 
       return {
-        ref: result.data.blob.ref,
+        ref: { $link: result.data.blob.ref.toString() },
         mimeType: result.data.blob.mimeType,
         size: result.data.blob.size,
       };