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

package/dist/index.d.ts

@@ -2355,7 +2355,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;
     /**
@@ -2461,7 +2486,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;
         /**
@@ -2703,13 +2753,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;
@@ -2902,6 +2986,56 @@ declare class ATProtoSDK {
      * ```
      */
     revokeSession(did: string): Promise<void>;
+    /**
+     * Gets the account email address from the authenticated session.
+     *
+     * This method retrieves the email address associated with the user's account
+     * by calling the `com.atproto.server.getSession` endpoint. The email will only
+     * be returned if the appropriate OAuth scope was granted during authorization.
+     *
+     * Required OAuth scopes:
+     * - **Granular permissions**: `account:email?action=read` or `account:email`
+     * - **Transitional permissions**: `transition:email`
+     *
+     * @param session - An authenticated OAuth session
+     * @returns A Promise resolving to email info, or `null` if permission not granted
+     * @throws {@link ValidationError} if the session is invalid
+     * @throws {@link NetworkError} if the API request fails
+     *
+     * @example Using granular permissions
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     *
+     * // Authorize with email scope
+     * const authUrl = await sdk.authorize("user.bsky.social", {
+     *   scope: ScopePresets.EMAIL_READ
+     * });
+     *
+     * // After callback...
+     * const emailInfo = await sdk.getAccountEmail(session);
+     * if (emailInfo) {
+     *   console.log(`Email: ${emailInfo.email}`);
+     *   console.log(`Confirmed: ${emailInfo.emailConfirmed}`);
+     * } else {
+     *   console.log("Email permission not granted");
+     * }
+     * ```
+     *
+     * @example Using transitional permissions (legacy)
+     * ```typescript
+     * // Authorize with transition:email scope
+     * const authUrl = await sdk.authorize("user.bsky.social", {
+     *   scope: "atproto transition:email"
+     * });
+     *
+     * // After callback...
+     * const emailInfo = await sdk.getAccountEmail(session);
+     * ```
+     */
+    getAccountEmail(session: Session): Promise<{
+        email: string;
+        emailConfirmed: boolean;
+    } | null>;
     /**
      * Creates a repository instance for data operations.
      *
@@ -3532,5 +3666,1047 @@ declare class InMemoryStateStore implements StateStore {
     clear(): void;
 }
 
-export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
-export type { ATProtoSDKConfig, AuthorizeOptions, BlobOperations, BlobRef, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertRights, HypercertWithMetadata, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, ProfileOperations, ProgressStep, RecordOperations, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, Session, SessionStore, StateStore, StrongRef, UpdateResult, ValidationResult };
+/**
+ * OAuth Scopes and Granular Permissions
+ *
+ * This module provides type-safe, Zod-validated OAuth scope and permission management
+ * for the ATProto SDK. It supports both legacy transitional scopes and the new
+ * granular permissions model.
+ *
+ * @see https://atproto.com/specs/oauth
+ * @see https://atproto.com/specs/permission
+ *
+ * @module auth/permissions
+ */
+
+/**
+ * Base OAuth scope - required for all sessions
+ *
+ * @constant
+ */
+declare const ATPROTO_SCOPE: "atproto";
+/**
+ * Transitional OAuth scopes for legacy compatibility.
+ *
+ * These scopes provide broad access and are maintained for backwards compatibility.
+ * New applications should use granular permissions instead.
+ *
+ * @deprecated Use granular permissions (account:*, repo:*, etc.) for better control
+ * @constant
+ */
+declare const TRANSITION_SCOPES: {
+    /** Broad PDS permissions including record creation, blob uploads, and preferences */
+    readonly GENERIC: "transition:generic";
+    /** Direct messages access (requires transition:generic) */
+    readonly CHAT: "transition:chat.bsky";
+    /** Email address and confirmation status */
+    readonly EMAIL: "transition:email";
+};
+/**
+ * Zod schema for transitional scopes.
+ *
+ * Validates that a scope string is one of the known transitional scopes.
+ *
+ * @example
+ * ```typescript
+ * TransitionScopeSchema.parse('transition:email'); // Valid
+ * TransitionScopeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+declare const TransitionScopeSchema: z.ZodEnum<["transition:generic", "transition:chat.bsky", "transition:email"]>;
+/**
+ * Type for transitional scopes inferred from schema.
+ */
+type TransitionScope = z.infer<typeof TransitionScopeSchema>;
+/**
+ * Zod schema for account permission attributes.
+ *
+ * Account attributes specify what aspect of the account is being accessed.
+ */
+declare const AccountAttrSchema: z.ZodEnum<["email", "repo"]>;
+/**
+ * Type for account attributes inferred from schema.
+ */
+type AccountAttr = z.infer<typeof AccountAttrSchema>;
+/**
+ * Zod schema for account actions.
+ *
+ * Account actions specify the level of access (read-only or management).
+ */
+declare const AccountActionSchema: z.ZodEnum<["read", "manage"]>;
+/**
+ * Type for account actions inferred from schema.
+ */
+type AccountAction = z.infer<typeof AccountActionSchema>;
+/**
+ * Zod schema for repository actions.
+ *
+ * Repository actions specify what operations can be performed on records.
+ */
+declare const RepoActionSchema: z.ZodEnum<["create", "update", "delete"]>;
+/**
+ * Type for repository actions inferred from schema.
+ */
+type RepoAction = z.infer<typeof RepoActionSchema>;
+/**
+ * Zod schema for identity permission attributes.
+ *
+ * Identity attributes specify what identity information can be managed.
+ */
+declare const IdentityAttrSchema: z.ZodEnum<["handle", "*"]>;
+/**
+ * Type for identity attributes inferred from schema.
+ */
+type IdentityAttr = z.infer<typeof IdentityAttrSchema>;
+/**
+ * Zod schema for MIME type patterns.
+ *
+ * Validates MIME type strings like "image/*" or "video/mp4".
+ *
+ * @example
+ * ```typescript
+ * MimeTypeSchema.parse('image/*'); // Valid
+ * MimeTypeSchema.parse('video/mp4'); // Valid
+ * MimeTypeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+declare const MimeTypeSchema: z.ZodString;
+/**
+ * Zod schema for NSID (Namespaced Identifier).
+ *
+ * NSIDs are reverse-DNS style identifiers used throughout ATProto
+ * (e.g., "app.bsky.feed.post" or "com.example.myrecord").
+ *
+ * @see https://atproto.com/specs/nsid
+ *
+ * @example
+ * ```typescript
+ * NsidSchema.parse('app.bsky.feed.post'); // Valid
+ * NsidSchema.parse('com.example.myrecord'); // Valid
+ * NsidSchema.parse('InvalidNSID'); // Throws ZodError
+ * ```
+ */
+declare const NsidSchema: z.ZodString;
+/**
+ * Zod schema for account permission.
+ *
+ * Account permissions control access to account-level information like email
+ * and repository management.
+ *
+ * @example Without action (read-only)
+ * ```typescript
+ * const input = { type: 'account', attr: 'email' };
+ * AccountPermissionSchema.parse(input); // Returns: "account:email"
+ * ```
+ *
+ * @example With action
+ * ```typescript
+ * const input = { type: 'account', attr: 'email', action: 'manage' };
+ * AccountPermissionSchema.parse(input); // Returns: "account:email?action=manage"
+ * ```
+ */
+declare const AccountPermissionSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"account">;
+    attr: z.ZodEnum<["email", "repo"]>;
+    action: z.ZodOptional<z.ZodEnum<["read", "manage"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "account";
+    attr: "email" | "repo";
+    action?: "read" | "manage" | undefined;
+}, {
+    type: "account";
+    attr: "email" | "repo";
+    action?: "read" | "manage" | undefined;
+}>, string, {
+    type: "account";
+    attr: "email" | "repo";
+    action?: "read" | "manage" | undefined;
+}>;
+/**
+ * Input type for account permission (before transform).
+ */
+type AccountPermissionInput = z.input<typeof AccountPermissionSchema>;
+/**
+ * Zod schema for repository permission.
+ *
+ * Repository permissions control write access to records by collection type.
+ * The collection must be a valid NSID or wildcard (*).
+ *
+ * @example Without actions (all actions allowed)
+ * ```typescript
+ * const input = { type: 'repo', collection: 'app.bsky.feed.post' };
+ * RepoPermissionSchema.parse(input); // Returns: "repo:app.bsky.feed.post"
+ * ```
+ *
+ * @example With specific actions
+ * ```typescript
+ * const input = {
+ *   type: 'repo',
+ *   collection: 'app.bsky.feed.post',
+ *   actions: ['create', 'update']
+ * };
+ * RepoPermissionSchema.parse(input); // Returns: "repo:app.bsky.feed.post?action=create&action=update"
+ * ```
+ *
+ * @example With wildcard collection
+ * ```typescript
+ * const input = { type: 'repo', collection: '*', actions: ['delete'] };
+ * RepoPermissionSchema.parse(input); // Returns: "repo:*?action=delete"
+ * ```
+ */
+declare const RepoPermissionSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"repo">;
+    collection: z.ZodUnion<[z.ZodString, z.ZodLiteral<"*">]>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodEnum<["create", "update", "delete"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "repo";
+    collection: string;
+    actions?: ("create" | "update" | "delete")[] | undefined;
+}, {
+    type: "repo";
+    collection: string;
+    actions?: ("create" | "update" | "delete")[] | undefined;
+}>, string, {
+    type: "repo";
+    collection: string;
+    actions?: ("create" | "update" | "delete")[] | undefined;
+}>;
+/**
+ * Input type for repository permission (before transform).
+ */
+type RepoPermissionInput = z.input<typeof RepoPermissionSchema>;
+/**
+ * Zod schema for blob permission.
+ *
+ * Blob permissions control media file uploads constrained by MIME type patterns.
+ *
+ * @example Single MIME type
+ * ```typescript
+ * const input = { type: 'blob', mimeTypes: ['image/*'] };
+ * BlobPermissionSchema.parse(input); // Returns: "blob:image/*"
+ * ```
+ *
+ * @example Multiple MIME types
+ * ```typescript
+ * const input = { type: 'blob', mimeTypes: ['image/*', 'video/*'] };
+ * BlobPermissionSchema.parse(input); // Returns: "blob?accept=image/*&accept=video/*"
+ * ```
+ */
+declare const BlobPermissionSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"blob">;
+    mimeTypes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "blob";
+    mimeTypes: string[];
+}, {
+    type: "blob";
+    mimeTypes: string[];
+}>, string, {
+    type: "blob";
+    mimeTypes: string[];
+}>;
+/**
+ * Input type for blob permission (before transform).
+ */
+type BlobPermissionInput = z.input<typeof BlobPermissionSchema>;
+/**
+ * Zod schema for RPC permission.
+ *
+ * RPC permissions control authenticated API calls to remote services.
+ * At least one of lexicon or aud must be restricted (both cannot be wildcards).
+ *
+ * @example Specific lexicon with wildcard audience
+ * ```typescript
+ * const input = {
+ *   type: 'rpc',
+ *   lexicon: 'com.atproto.repo.createRecord',
+ *   aud: '*'
+ * };
+ * RpcPermissionSchema.parse(input);
+ * // Returns: "rpc:com.atproto.repo.createRecord?aud=*"
+ * ```
+ *
+ * @example With specific audience
+ * ```typescript
+ * const input = {
+ *   type: 'rpc',
+ *   lexicon: 'com.atproto.repo.createRecord',
+ *   aud: 'did:web:api.example.com',
+ *   inheritAud: true
+ * };
+ * RpcPermissionSchema.parse(input);
+ * // Returns: "rpc:com.atproto.repo.createRecord?aud=did%3Aweb%3Aapi.example.com&inheritAud=true"
+ * ```
+ */
+declare const RpcPermissionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"rpc">;
+    lexicon: z.ZodUnion<[z.ZodString, z.ZodLiteral<"*">]>;
+    aud: z.ZodString;
+    inheritAud: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}>, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}>, string, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}>;
+/**
+ * Input type for RPC permission (before transform).
+ */
+type RpcPermissionInput = z.input<typeof RpcPermissionSchema>;
+/**
+ * Zod schema for identity permission.
+ *
+ * Identity permissions control access to DID documents and handles.
+ *
+ * @example Handle management
+ * ```typescript
+ * const input = { type: 'identity', attr: 'handle' };
+ * IdentityPermissionSchema.parse(input); // Returns: "identity:handle"
+ * ```
+ *
+ * @example All identity attributes
+ * ```typescript
+ * const input = { type: 'identity', attr: '*' };
+ * IdentityPermissionSchema.parse(input); // Returns: "identity:*"
+ * ```
+ */
+declare const IdentityPermissionSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"identity">;
+    attr: z.ZodEnum<["handle", "*"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "identity";
+    attr: "handle" | "*";
+}, {
+    type: "identity";
+    attr: "handle" | "*";
+}>, string, {
+    type: "identity";
+    attr: "handle" | "*";
+}>;
+/**
+ * Input type for identity permission (before transform).
+ */
+type IdentityPermissionInput = z.input<typeof IdentityPermissionSchema>;
+/**
+ * Zod schema for permission set inclusion.
+ *
+ * Include permissions reference permission sets bundled under a single NSID.
+ *
+ * @example Without audience
+ * ```typescript
+ * const input = { type: 'include', nsid: 'com.example.authBasicFeatures' };
+ * IncludePermissionSchema.parse(input);
+ * // Returns: "include:com.example.authBasicFeatures"
+ * ```
+ *
+ * @example With audience
+ * ```typescript
+ * const input = {
+ *   type: 'include',
+ *   nsid: 'com.example.authBasicFeatures',
+ *   aud: 'did:web:api.example.com'
+ * };
+ * IncludePermissionSchema.parse(input);
+ * // Returns: "include:com.example.authBasicFeatures?aud=did%3Aweb%3Aapi.example.com"
+ * ```
+ */
+declare const IncludePermissionSchema: z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"include">;
+    nsid: z.ZodString;
+    aud: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "include";
+    nsid: string;
+    aud?: string | undefined;
+}, {
+    type: "include";
+    nsid: string;
+    aud?: string | undefined;
+}>, string, {
+    type: "include";
+    nsid: string;
+    aud?: string | undefined;
+}>;
+/**
+ * Input type for include permission (before transform).
+ */
+type IncludePermissionInput = z.input<typeof IncludePermissionSchema>;
+/**
+ * Union schema for all permission types.
+ *
+ * This schema accepts any of the supported permission types and validates
+ * them according to their specific rules.
+ */
+declare const PermissionSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"account">;
+    attr: z.ZodEnum<["email", "repo"]>;
+    action: z.ZodOptional<z.ZodEnum<["read", "manage"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "account";
+    attr: "email" | "repo";
+    action?: "read" | "manage" | undefined;
+}, {
+    type: "account";
+    attr: "email" | "repo";
+    action?: "read" | "manage" | undefined;
+}>, string, {
+    type: "account";
+    attr: "email" | "repo";
+    action?: "read" | "manage" | undefined;
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"repo">;
+    collection: z.ZodUnion<[z.ZodString, z.ZodLiteral<"*">]>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodEnum<["create", "update", "delete"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "repo";
+    collection: string;
+    actions?: ("create" | "update" | "delete")[] | undefined;
+}, {
+    type: "repo";
+    collection: string;
+    actions?: ("create" | "update" | "delete")[] | undefined;
+}>, string, {
+    type: "repo";
+    collection: string;
+    actions?: ("create" | "update" | "delete")[] | undefined;
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"blob">;
+    mimeTypes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "blob";
+    mimeTypes: string[];
+}, {
+    type: "blob";
+    mimeTypes: string[];
+}>, string, {
+    type: "blob";
+    mimeTypes: string[];
+}>, z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"rpc">;
+    lexicon: z.ZodUnion<[z.ZodString, z.ZodLiteral<"*">]>;
+    aud: z.ZodString;
+    inheritAud: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}>, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}>, string, {
+    type: "rpc";
+    lexicon: string;
+    aud: string;
+    inheritAud?: boolean | undefined;
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"identity">;
+    attr: z.ZodEnum<["handle", "*"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "identity";
+    attr: "handle" | "*";
+}, {
+    type: "identity";
+    attr: "handle" | "*";
+}>, string, {
+    type: "identity";
+    attr: "handle" | "*";
+}>, z.ZodEffects<z.ZodObject<{
+    type: z.ZodLiteral<"include">;
+    nsid: z.ZodString;
+    aud: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "include";
+    nsid: string;
+    aud?: string | undefined;
+}, {
+    type: "include";
+    nsid: string;
+    aud?: string | undefined;
+}>, string, {
+    type: "include";
+    nsid: string;
+    aud?: string | undefined;
+}>]>;
+/**
+ * Input type for any permission (before transform).
+ */
+type PermissionInput = z.input<typeof PermissionSchema>;
+/**
+ * Output type for any permission (after transform).
+ */
+type Permission = z.output<typeof PermissionSchema>;
+/**
+ * Fluent builder for constructing OAuth permission arrays.
+ *
+ * This class provides a convenient, type-safe way to build arrays of permissions
+ * using method chaining.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const builder = new PermissionBuilder()
+ *   .accountEmail('read')
+ *   .repoWrite('app.bsky.feed.post')
+ *   .blob(['image/*', 'video/*']);
+ *
+ * const permissions = builder.build();
+ * // Returns: ['account:email?action=read', 'repo:app.bsky.feed.post?action=create&action=update', 'blob:image/*,video/*']
+ * ```
+ *
+ * @example With transitional scopes
+ * ```typescript
+ * const builder = new PermissionBuilder()
+ *   .transition('email')
+ *   .transition('generic');
+ *
+ * const scopes = builder.build();
+ * // Returns: ['transition:email', 'transition:generic']
+ * ```
+ */
+declare class PermissionBuilder {
+    private permissions;
+    /**
+     * Add a transitional scope.
+     *
+     * @param scope - The transitional scope name ('email', 'generic', or 'chat.bsky')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.transition('email').transition('generic');
+     * ```
+     */
+    transition(scope: "email" | "generic" | "chat.bsky"): this;
+    /**
+     * Add an account permission.
+     *
+     * @param attr - The account attribute ('email' or 'repo')
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountEmail('read').accountRepo('manage');
+     * ```
+     */
+    account(attr: z.infer<typeof AccountAttrSchema>, action?: z.infer<typeof AccountActionSchema>): this;
+    /**
+     * Convenience method for account:email permission.
+     *
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountEmail('read');
+     * ```
+     */
+    accountEmail(action?: z.infer<typeof AccountActionSchema>): this;
+    /**
+     * Convenience method for account:repo permission.
+     *
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountRepo('manage');
+     * ```
+     */
+    accountRepo(action?: z.infer<typeof AccountActionSchema>): this;
+    /**
+     * Add a repository permission.
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @param actions - Optional array of actions ('create', 'update', 'delete')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repo('app.bsky.feed.post', ['create', 'update']);
+     * ```
+     */
+    repo(collection: string, actions?: z.infer<typeof RepoActionSchema>[]): this;
+    /**
+     * Convenience method for repository write permissions (create + update).
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repoWrite('app.bsky.feed.post');
+     * ```
+     */
+    repoWrite(collection: string): this;
+    /**
+     * Convenience method for repository read permission (no actions).
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repoRead('app.bsky.feed.post');
+     * ```
+     */
+    repoRead(collection: string): this;
+    /**
+     * Convenience method for full repository permissions (create + update + delete).
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repoFull('app.bsky.feed.post');
+     * ```
+     */
+    repoFull(collection: string): this;
+    /**
+     * Add a blob permission.
+     *
+     * @param mimeTypes - Array of MIME types or a single MIME type
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.blob(['image/*', 'video/*']);
+     * builder.blob('image/*');
+     * ```
+     */
+    blob(mimeTypes: string | string[]): this;
+    /**
+     * Add an RPC permission.
+     *
+     * @param lexicon - The NSID of the lexicon or '*' for all
+     * @param aud - The audience (DID or URL)
+     * @param inheritAud - Whether to inherit audience
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.rpc('com.atproto.repo.createRecord', 'did:web:api.example.com');
+     * ```
+     */
+    rpc(lexicon: string, aud: string, inheritAud?: boolean): this;
+    /**
+     * Add an identity permission.
+     *
+     * @param attr - The identity attribute ('handle' or '*')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.identity('handle');
+     * ```
+     */
+    identity(attr: z.infer<typeof IdentityAttrSchema>): this;
+    /**
+     * Add an include permission.
+     *
+     * @param nsid - The NSID of the scope set to include
+     * @param aud - Optional audience restriction
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.include('com.example.authBasicFeatures');
+     * ```
+     */
+    include(nsid: string, aud?: string): this;
+    /**
+     * Add a custom permission string directly (bypasses validation).
+     *
+     * Use this for testing or special cases where you need to add
+     * a permission that doesn't fit the standard types.
+     *
+     * @param permission - The permission string
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.custom('atproto');
+     * ```
+     */
+    custom(permission: string): this;
+    /**
+     * Add the base atproto scope.
+     *
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.atproto();
+     * ```
+     */
+    atproto(): this;
+    /**
+     * Build and return the array of permission strings.
+     *
+     * @returns Array of permission strings
+     *
+     * @example
+     * ```typescript
+     * const permissions = builder.build();
+     * ```
+     */
+    build(): string[];
+    /**
+     * Clear all permissions from the builder.
+     *
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.clear().accountEmail('read');
+     * ```
+     */
+    clear(): this;
+    /**
+     * Get the current number of permissions.
+     *
+     * @returns The number of permissions
+     *
+     * @example
+     * ```typescript
+     * const count = builder.count();
+     * ```
+     */
+    count(): number;
+}
+/**
+ * Build a scope string from an array of permissions.
+ *
+ * This is a convenience function that joins permission strings with spaces,
+ * which is the standard format for OAuth scope parameters.
+ *
+ * @param permissions - Array of permission strings
+ * @returns Space-separated scope string
+ *
+ * @example
+ * ```typescript
+ * const permissions = ['account:email?action=read', 'repo:app.bsky.feed.post'];
+ * const scope = buildScope(permissions);
+ * // Returns: "account:email?action=read repo:app.bsky.feed.post"
+ * ```
+ */
+declare function buildScope(permissions: string[]): string;
+/**
+ * Pre-built scope presets for common use cases.
+ *
+ * These presets provide ready-to-use permission sets for typical application scenarios.
+ */
+declare const ScopePresets: {
+    /**
+     * Email access scope - allows reading user's email address.
+     *
+     * Includes:
+     * - account:email?action=read
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.EMAIL_READ;
+     * // Use in OAuth flow to request email access
+     * ```
+     */
+    readonly EMAIL_READ: string;
+    /**
+     * Profile read scope - allows reading user's profile.
+     *
+     * Includes:
+     * - repo:app.bsky.actor.profile (read-only)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.PROFILE_READ;
+     * ```
+     */
+    readonly PROFILE_READ: string;
+    /**
+     * Profile write scope - allows updating user's profile.
+     *
+     * Includes:
+     * - repo:app.bsky.actor.profile (create + update)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.PROFILE_WRITE;
+     * ```
+     */
+    readonly PROFILE_WRITE: string;
+    /**
+     * Post creation scope - allows creating and updating posts.
+     *
+     * Includes:
+     * - repo:app.bsky.feed.post (create + update)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.POST_WRITE;
+     * ```
+     */
+    readonly POST_WRITE: string;
+    /**
+     * Social interactions scope - allows liking, reposting, and following.
+     *
+     * Includes:
+     * - repo:app.bsky.feed.like (create + update)
+     * - repo:app.bsky.feed.repost (create + update)
+     * - repo:app.bsky.graph.follow (create + update)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.SOCIAL_WRITE;
+     * ```
+     */
+    readonly SOCIAL_WRITE: string;
+    /**
+     * Media upload scope - allows uploading images and videos.
+     *
+     * Includes:
+     * - blob permissions for image/* and video/*
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.MEDIA_UPLOAD;
+     * ```
+     */
+    readonly MEDIA_UPLOAD: string;
+    /**
+     * Image upload only scope - allows uploading images.
+     *
+     * Includes:
+     * - blob:image/*
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.IMAGE_UPLOAD;
+     * ```
+     */
+    readonly IMAGE_UPLOAD: string;
+    /**
+     * Posting app scope - full posting capabilities including media.
+     *
+     * Includes:
+     * - repo:app.bsky.feed.post (create + update)
+     * - repo:app.bsky.feed.like (create + update)
+     * - repo:app.bsky.feed.repost (create + update)
+     * - blob permissions for image/* and video/*
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.POSTING_APP;
+     * ```
+     */
+    readonly POSTING_APP: string;
+    /**
+     * Read-only app scope - allows reading all repository data.
+     *
+     * Includes:
+     * - repo:* (read-only, no actions)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.READ_ONLY;
+     * ```
+     */
+    readonly READ_ONLY: string;
+    /**
+     * Full access scope - allows all repository operations.
+     *
+     * Includes:
+     * - repo:* (create + update + delete)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.FULL_ACCESS;
+     * ```
+     */
+    readonly FULL_ACCESS: string;
+    /**
+     * Email + Profile scope - common combination for user identification.
+     *
+     * Includes:
+     * - account:email?action=read
+     * - repo:app.bsky.actor.profile (read-only)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.EMAIL_AND_PROFILE;
+     * ```
+     */
+    readonly EMAIL_AND_PROFILE: string;
+    /**
+     * Transitional email scope (legacy).
+     *
+     * Uses the transitional scope format for backward compatibility.
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.TRANSITION_EMAIL;
+     * ```
+     */
+    readonly TRANSITION_EMAIL: string;
+    /**
+     * Transitional generic scope (legacy).
+     *
+     * Uses the transitional scope format for backward compatibility.
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.TRANSITION_GENERIC;
+     * ```
+     */
+    readonly TRANSITION_GENERIC: string;
+};
+/**
+ * Parse a scope string into an array of individual permissions.
+ *
+ * This splits a space-separated scope string into individual permission strings.
+ *
+ * @param scope - Space-separated scope string
+ * @returns Array of permission strings
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post";
+ * const permissions = parseScope(scope);
+ * // Returns: ['account:email?action=read', 'repo:app.bsky.feed.post']
+ * ```
+ */
+declare function parseScope(scope: string): string[];
+/**
+ * Check if a scope string contains a specific permission.
+ *
+ * This function performs exact string matching. For more advanced
+ * permission checking (e.g., wildcard matching), you'll need to
+ * implement custom logic.
+ *
+ * @param scope - Space-separated scope string
+ * @param permission - The permission to check for
+ * @returns True if the scope contains the permission
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post";
+ * hasPermission(scope, "account:email?action=read"); // true
+ * hasPermission(scope, "account:repo"); // false
+ * ```
+ */
+declare function hasPermission(scope: string, permission: string): boolean;
+/**
+ * Check if a scope string contains all of the specified permissions.
+ *
+ * @param scope - Space-separated scope string
+ * @param requiredPermissions - Array of permissions to check for
+ * @returns True if the scope contains all required permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post blob:image/*";
+ * hasAllPermissions(scope, ["account:email?action=read", "blob:image/*"]); // true
+ * hasAllPermissions(scope, ["account:email?action=read", "account:repo"]); // false
+ * ```
+ */
+declare function hasAllPermissions(scope: string, requiredPermissions: string[]): boolean;
+/**
+ * Check if a scope string contains any of the specified permissions.
+ *
+ * @param scope - Space-separated scope string
+ * @param checkPermissions - Array of permissions to check for
+ * @returns True if the scope contains at least one of the permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post";
+ * hasAnyPermission(scope, ["account:email?action=read", "account:repo"]); // true
+ * hasAnyPermission(scope, ["account:repo", "identity:handle"]); // false
+ * ```
+ */
+declare function hasAnyPermission(scope: string, checkPermissions: string[]): boolean;
+/**
+ * Merge multiple scope strings into a single scope string with deduplicated permissions.
+ *
+ * @param scopes - Array of scope strings to merge
+ * @returns Merged scope string with unique permissions
+ *
+ * @example
+ * ```typescript
+ * const scope1 = "account:email?action=read repo:app.bsky.feed.post";
+ * const scope2 = "repo:app.bsky.feed.post blob:image/*";
+ * const merged = mergeScopes([scope1, scope2]);
+ * // Returns: "account:email?action=read repo:app.bsky.feed.post blob:image/*"
+ * ```
+ */
+declare function mergeScopes(scopes: string[]): string;
+/**
+ * Remove specific permissions from a scope string.
+ *
+ * @param scope - Space-separated scope string
+ * @param permissionsToRemove - Array of permissions to remove
+ * @returns New scope string without the specified permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post blob:image/*";
+ * const filtered = removePermissions(scope, ["blob:image/*"]);
+ * // Returns: "account:email?action=read repo:app.bsky.feed.post"
+ * ```
+ */
+declare function removePermissions(scope: string, permissionsToRemove: string[]): string;
+/**
+ * Validate that all permissions in a scope string are well-formed.
+ *
+ * This checks that each permission matches expected patterns for transitional
+ * or granular permissions. It does NOT validate against the full Zod schemas.
+ *
+ * @param scope - Space-separated scope string
+ * @returns Object with isValid flag and array of invalid permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read invalid:permission";
+ * const result = validateScope(scope);
+ * // Returns: { isValid: false, invalidPermissions: ['invalid:permission'] }
+ * ```
+ */
+declare function validateScope(scope: string): {
+    isValid: boolean;
+    invalidPermissions: string[];
+};
+
+export { ATPROTO_SCOPE, ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AccountActionSchema, AccountAttrSchema, AccountPermissionSchema, AuthenticationError, BlobPermissionSchema, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, IdentityAttrSchema, IdentityPermissionSchema, InMemorySessionStore, InMemoryStateStore, IncludePermissionSchema, LexiconRegistry, MimeTypeSchema, NetworkError, NsidSchema, OAuthConfigSchema, OrganizationSchema, PermissionBuilder, PermissionSchema, RepoActionSchema, RepoPermissionSchema, Repository, RpcPermissionSchema, SDSRequiredError, ScopePresets, ServerConfigSchema, SessionExpiredError, TRANSITION_SCOPES, TimeoutConfigSchema, TransitionScopeSchema, ValidationError, buildScope, createATProtoSDK, hasAllPermissions, hasAnyPermission, hasPermission, mergeScopes, parseScope, removePermissions, validateScope };
+export type { ATProtoSDKConfig, AccountAction, AccountAttr, AccountPermissionInput, AuthorizeOptions, BlobOperations, BlobPermissionInput, BlobRef, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertRights, HypercertWithMetadata, IdentityAttr, IdentityPermissionInput, IncludePermissionInput, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, Permission, PermissionInput, ProfileOperations, ProgressStep, RecordOperations, RepoAction, RepoPermissionInput, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, RpcPermissionInput, Session, SessionStore, StateStore, StrongRef, TransitionScope, UpdateResult, ValidationResult };