feat(permissions): add scope presets for common use cases

- Add ScopePresets object with 14 pre-built permission sets
- Include EMAIL_READ, PROFILE_READ/WRITE, POST_WRITE presets
- Add SOCIAL_WRITE for likes/reposts/follows
- Add MEDIA_UPLOAD and IMAGE_UPLOAD presets
- Add POSTING_APP preset combining posts and media
- Add READ_ONLY and FULL_ACCESS presets
- Include EMAIL_AND_PROFILE combo preset
- Add transitional scope presets for backward compatibility
- Add 18 comprehensive tests for all presets
- All 167 tests passing

Author: bitbeckers

packages/sdk-core/src/auth/permissions.ts

@@ -769,6 +769,202 @@ export function buildScope(permissions: string[]): string {
   return permissions.join(" ");
 }
 
+/**
+ * Pre-built scope presets for common use cases.
+ *
+ * These presets provide ready-to-use permission sets for typical application scenarios.
+ */
+export 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
+   * ```
+   */
+  EMAIL_READ: buildScope(new PermissionBuilder().accountEmail("read").build()),
+
+  /**
+   * Profile read scope - allows reading user's profile.
+   *
+   * Includes:
+   * - repo:app.bsky.actor.profile (read-only)
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.PROFILE_READ;
+   * ```
+   */
+  PROFILE_READ: buildScope(new PermissionBuilder().repoRead("app.bsky.actor.profile").build()),
+
+  /**
+   * Profile write scope - allows updating user's profile.
+   *
+   * Includes:
+   * - repo:app.bsky.actor.profile (create + update)
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.PROFILE_WRITE;
+   * ```
+   */
+  PROFILE_WRITE: buildScope(new PermissionBuilder().repoWrite("app.bsky.actor.profile").build()),
+
+  /**
+   * Post creation scope - allows creating and updating posts.
+   *
+   * Includes:
+   * - repo:app.bsky.feed.post (create + update)
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.POST_WRITE;
+   * ```
+   */
+  POST_WRITE: buildScope(new PermissionBuilder().repoWrite("app.bsky.feed.post").build()),
+
+  /**
+   * 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;
+   * ```
+   */
+  SOCIAL_WRITE: buildScope(
+    new PermissionBuilder()
+      .repoWrite("app.bsky.feed.like")
+      .repoWrite("app.bsky.feed.repost")
+      .repoWrite("app.bsky.graph.follow")
+      .build(),
+  ),
+
+  /**
+   * Media upload scope - allows uploading images and videos.
+   *
+   * Includes:
+   * - blob permissions for image/* and video/*
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.MEDIA_UPLOAD;
+   * ```
+   */
+  MEDIA_UPLOAD: buildScope(new PermissionBuilder().blob(["image/*", "video/*"]).build()),
+
+  /**
+   * Image upload only scope - allows uploading images.
+   *
+   * Includes:
+   * - blob:image/*
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.IMAGE_UPLOAD;
+   * ```
+   */
+  IMAGE_UPLOAD: buildScope(new PermissionBuilder().blob("image/*").build()),
+
+  /**
+   * 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;
+   * ```
+   */
+  POSTING_APP: buildScope(
+    new PermissionBuilder()
+      .repoWrite("app.bsky.feed.post")
+      .repoWrite("app.bsky.feed.like")
+      .repoWrite("app.bsky.feed.repost")
+      .blob(["image/*", "video/*"])
+      .build(),
+  ),
+
+  /**
+   * Read-only app scope - allows reading all repository data.
+   *
+   * Includes:
+   * - repo:* (read-only, no actions)
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.READ_ONLY;
+   * ```
+   */
+  READ_ONLY: buildScope(new PermissionBuilder().repoRead("*").build()),
+
+  /**
+   * Full access scope - allows all repository operations.
+   *
+   * Includes:
+   * - repo:* (create + update + delete)
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.FULL_ACCESS;
+   * ```
+   */
+  FULL_ACCESS: buildScope(new PermissionBuilder().repoFull("*").build()),
+
+  /**
+   * 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;
+   * ```
+   */
+  EMAIL_AND_PROFILE: buildScope(
+    new PermissionBuilder().accountEmail("read").repoRead("app.bsky.actor.profile").build(),
+  ),
+
+  /**
+   * Transitional email scope (legacy).
+   *
+   * Uses the transitional scope format for backward compatibility.
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.TRANSITION_EMAIL;
+   * ```
+   */
+  TRANSITION_EMAIL: buildScope(new PermissionBuilder().transition("email").build()),
+
+  /**
+   * Transitional generic scope (legacy).
+   *
+   * Uses the transitional scope format for backward compatibility.
+   *
+   * @example
+   * ```typescript
+   * const scope = ScopePresets.TRANSITION_GENERIC;
+   * ```
+   */
+  TRANSITION_GENERIC: buildScope(new PermissionBuilder().transition("generic").build()),
+} as const;
+
 /**
  * Parse a scope string into an array of individual permissions.
  *

packages/sdk-core/tests/auth/permissions.test.ts

@@ -17,6 +17,7 @@ import {
   IncludePermissionSchema,
   PermissionSchema,
   PermissionBuilder,
+  ScopePresets,
   buildScope,
   parseScope,
   hasPermission,
@@ -1121,3 +1122,109 @@ describe("Scope Utility Functions", () => {
     });
   });
 });
+
+describe("ScopePresets", () => {
+  describe("Basic Presets", () => {
+    it("should provide EMAIL_READ preset", () => {
+      expect(ScopePresets.EMAIL_READ).toBe("account:email?action=read");
+    });
+
+    it("should provide PROFILE_READ preset", () => {
+      expect(ScopePresets.PROFILE_READ).toBe("repo:app.bsky.actor.profile");
+    });
+
+    it("should provide PROFILE_WRITE preset", () => {
+      expect(ScopePresets.PROFILE_WRITE).toBe("repo:app.bsky.actor.profile?action=create&action=update");
+    });
+
+    it("should provide POST_WRITE preset", () => {
+      expect(ScopePresets.POST_WRITE).toBe("repo:app.bsky.feed.post?action=create&action=update");
+    });
+
+    it("should provide IMAGE_UPLOAD preset", () => {
+      expect(ScopePresets.IMAGE_UPLOAD).toBe("blob:image/*");
+    });
+
+    it("should provide MEDIA_UPLOAD preset", () => {
+      expect(ScopePresets.MEDIA_UPLOAD).toBe("blob?accept=image%2F*&accept=video%2F*");
+    });
+  });
+
+  describe("Complex Presets", () => {
+    it("should provide SOCIAL_WRITE preset", () => {
+      const permissions = parseScope(ScopePresets.SOCIAL_WRITE);
+      expect(permissions).toHaveLength(3);
+      expect(permissions).toContain("repo:app.bsky.feed.like?action=create&action=update");
+      expect(permissions).toContain("repo:app.bsky.feed.repost?action=create&action=update");
+      expect(permissions).toContain("repo:app.bsky.graph.follow?action=create&action=update");
+    });
+
+    it("should provide POSTING_APP preset", () => {
+      const permissions = parseScope(ScopePresets.POSTING_APP);
+      expect(permissions).toHaveLength(4);
+      expect(permissions).toContain("repo:app.bsky.feed.post?action=create&action=update");
+      expect(permissions).toContain("repo:app.bsky.feed.like?action=create&action=update");
+      expect(permissions).toContain("repo:app.bsky.feed.repost?action=create&action=update");
+      expect(permissions).toContain("blob?accept=image%2F*&accept=video%2F*");
+    });
+
+    it("should provide EMAIL_AND_PROFILE preset", () => {
+      const permissions = parseScope(ScopePresets.EMAIL_AND_PROFILE);
+      expect(permissions).toHaveLength(2);
+      expect(permissions).toContain("account:email?action=read");
+      expect(permissions).toContain("repo:app.bsky.actor.profile");
+    });
+  });
+
+  describe("Access Level Presets", () => {
+    it("should provide READ_ONLY preset", () => {
+      expect(ScopePresets.READ_ONLY).toBe("repo:*");
+    });
+
+    it("should provide FULL_ACCESS preset", () => {
+      expect(ScopePresets.FULL_ACCESS).toBe("repo:*?action=create&action=update&action=delete");
+    });
+  });
+
+  describe("Transitional Presets", () => {
+    it("should provide TRANSITION_EMAIL preset", () => {
+      expect(ScopePresets.TRANSITION_EMAIL).toBe("transition:email");
+    });
+
+    it("should provide TRANSITION_GENERIC preset", () => {
+      expect(ScopePresets.TRANSITION_GENERIC).toBe("transition:generic");
+    });
+  });
+
+  describe("Preset Usage", () => {
+    it("should work with parseScope", () => {
+      const permissions = parseScope(ScopePresets.POSTING_APP);
+      expect(permissions.length).toBeGreaterThan(0);
+    });
+
+    it("should work with hasPermission", () => {
+      expect(hasPermission(ScopePresets.EMAIL_READ, "account:email?action=read")).toBe(true);
+      expect(hasPermission(ScopePresets.EMAIL_READ, "account:repo")).toBe(false);
+    });
+
+    it("should work with mergeScopes", () => {
+      const merged = mergeScopes([ScopePresets.EMAIL_READ, ScopePresets.POST_WRITE]);
+      expect(hasPermission(merged, "account:email?action=read")).toBe(true);
+      expect(hasPermission(merged, "repo:app.bsky.feed.post?action=create&action=update")).toBe(true);
+    });
+
+    it("should be valid scopes", () => {
+      expect(validateScope(ScopePresets.EMAIL_READ).isValid).toBe(true);
+      expect(validateScope(ScopePresets.POSTING_APP).isValid).toBe(true);
+      expect(validateScope(ScopePresets.FULL_ACCESS).isValid).toBe(true);
+      expect(validateScope(ScopePresets.TRANSITION_EMAIL).isValid).toBe(true);
+    });
+  });
+
+  describe("Preset Immutability", () => {
+    it("should be readonly (const assertion)", () => {
+      expect(typeof ScopePresets.EMAIL_READ).toBe("string");
+      expect(typeof ScopePresets.POSTING_APP).toBe("string");
+    });
+  });
+});