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

package/tests/auth/OAuthClient.test.ts

@@ -0,0 +1,164 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { OAuthClient } from "../../src/auth/OAuthClient.js";
+import { AuthenticationError } from "../../src/core/errors.js";
+import { createTestConfig, createTestConfigAsync } from "../utils/fixtures.js";
+import { InMemorySessionStore, InMemoryStateStore } from "../utils/mocks.js";
+
+describe("OAuthClient", () => {
+  let config: ReturnType<typeof createTestConfig>;
+
+  beforeEach(() => {
+    config = createTestConfig();
+  });
+
+  describe("constructor", () => {
+    it("should initialize with valid config", () => {
+      expect(() => new OAuthClient(config)).not.toThrow();
+    });
+
+    it("should throw AuthenticationError for invalid JWK", async () => {
+      const invalidConfig = await createTestConfigAsync({
+        oauth: {
+          ...config.oauth,
+          jwkPrivate: "invalid json",
+        },
+      });
+
+      expect(() => new OAuthClient(invalidConfig)).toThrow(AuthenticationError);
+      expect(() => new OAuthClient(invalidConfig)).toThrow("Failed to parse JWK private key");
+    });
+
+    it("should use custom fetch handler if provided", async () => {
+      const customFetch = vi.fn();
+      const configWithFetch = await createTestConfigAsync({
+        fetch: customFetch,
+      });
+      const client = new OAuthClient(configWithFetch);
+      expect(client).toBeDefined();
+    });
+
+    it("should use custom timeout configuration", async () => {
+      const configWithTimeout = await createTestConfigAsync({
+        timeouts: {
+          pdsMetadata: 60000,
+          apiRequests: 45000,
+        },
+      });
+      expect(() => new OAuthClient(configWithTimeout)).not.toThrow();
+    });
+  });
+
+  describe("authorize", () => {
+    it("should throw AuthenticationError for invalid identifier", async () => {
+      const client = new OAuthClient(config);
+      // Note: This will fail because we don't have a real PDS to connect to
+      // But we can test that it properly wraps errors
+      await expect(client.authorize("invalid-handle")).rejects.toThrow(AuthenticationError);
+    });
+
+    it("should use custom scope if provided", async () => {
+      const client = new OAuthClient(config);
+      // This will fail due to network, but we can verify the error handling
+      await expect(client.authorize("test.bsky.social", { scope: "custom-scope" })).rejects.toThrow();
+    });
+  });
+
+  describe("callback", () => {
+    it("should throw AuthenticationError for OAuth error params", async () => {
+      const client = new OAuthClient(config);
+      const params = new URLSearchParams({
+        error: "access_denied",
+        error_description: "User denied access",
+      });
+
+      await expect(client.callback(params)).rejects.toThrow(AuthenticationError);
+      await expect(client.callback(params)).rejects.toThrow("User denied access");
+    });
+
+    it("should throw AuthenticationError for missing code", async () => {
+      const client = new OAuthClient(config);
+      const params = new URLSearchParams({
+        state: "test-state",
+        // Missing 'code' parameter
+      });
+
+      // This will fail because callback needs valid OAuth params
+      await expect(client.callback(params)).rejects.toThrow();
+    });
+  });
+
+  describe("restore", () => {
+    it("should return null for non-existent session", async () => {
+      const client = new OAuthClient(config);
+      // Use a valid DID format (did:plc needs 32 char base32 suffix)
+      const validDid = "did:plc:abcdefghijklmnopqrstuvwxyz123456";
+      // This will fail due to network/DID validation, but we can verify error handling
+      await expect(client.restore(validDid)).rejects.toThrow();
+    });
+
+    it("should throw AuthenticationError for invalid DID", async () => {
+      const client = new OAuthClient(config);
+      // Invalid DID format
+      await expect(client.restore("did:plc:test")).rejects.toThrow(AuthenticationError);
+    });
+  });
+
+  describe("revoke", () => {
+    it("should not throw for non-existent session", async () => {
+      const client = new OAuthClient(config);
+      // Revoking a non-existent session should not throw
+      // Use valid DID format - revoke will fail due to network, but error handling is tested
+      const validDid = "did:plc:abcdefghijklmnopqrstuvwxyz123456";
+      await expect(client.revoke(validDid)).rejects.toThrow();
+    });
+  });
+
+  describe("storage integration", () => {
+    it("should use provided session store", async () => {
+      const sessionStore = new InMemorySessionStore();
+      const configWithStore = await createTestConfigAsync({
+        storage: {
+          sessionStore,
+          stateStore: new InMemoryStateStore(),
+        },
+      });
+
+      const client = new OAuthClient(configWithStore);
+      // Verify client is created with custom store
+      expect(client).toBeDefined();
+      // Note: Actual restore will fail due to network/DID validation,
+      // but the store integration is verified by client creation
+    });
+
+    it("should use provided state store", async () => {
+      const stateStore = new InMemoryStateStore();
+      const configWithStore = await createTestConfigAsync({
+        storage: {
+          sessionStore: new InMemorySessionStore(),
+          stateStore,
+        },
+      });
+
+      const client = new OAuthClient(configWithStore);
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe("logger integration", () => {
+    it("should use provided logger", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const configWithLogger = await createTestConfigAsync({ logger });
+
+      const client = new OAuthClient(configWithLogger);
+      // Try an operation that should log (will fail but should log)
+      try {
+        await client.restore("did:plc:test");
+      } catch {
+        // Expected to fail
+      }
+      // Logger should have been called during initialization or error handling
+      expect(logger.logs.length).toBeGreaterThan(0);
+    });
+  });
+});

package/tests/core/SDK.test.ts

@@ -0,0 +1,176 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ATProtoSDK, createATProtoSDK } from "../../src/core/SDK.js";
+import { ValidationError } from "../../src/core/errors.js";
+import { createTestConfigAsync } from "../utils/fixtures.js";
+import { InMemorySessionStore, InMemoryStateStore } from "../utils/mocks.js";
+
+describe("ATProtoSDK", () => {
+  let config: Awaited<ReturnType<typeof createTestConfigAsync>>;
+
+  beforeEach(async () => {
+    config = await createTestConfigAsync();
+  });
+
+  describe("constructor", () => {
+    it("should create SDK instance with valid config", () => {
+      const sdk = new ATProtoSDK(config);
+      expect(sdk).toBeInstanceOf(ATProtoSDK);
+    });
+
+    it("should validate config with Zod schema", () => {
+      const invalidConfig = {
+        ...config,
+        oauth: {
+          ...config.oauth,
+          clientId: "not-a-url", // Invalid URL
+        },
+      };
+
+      expect(() => new ATProtoSDK(invalidConfig)).toThrow(ValidationError);
+      expect(() => new ATProtoSDK(invalidConfig)).toThrow("Invalid SDK configuration");
+    });
+
+    it("should accept optional cache", async () => {
+      const { InMemoryCache } = await import("../utils/mocks.js");
+      const cache = new InMemoryCache();
+      const configWithCache = await createTestConfigAsync({ cache });
+      expect(() => new ATProtoSDK(configWithCache)).not.toThrow();
+    });
+
+    it("should accept optional logger", async () => {
+      const { MockLogger } = await import("../utils/mocks.js");
+      const logger = new MockLogger();
+      const configWithLogger = await createTestConfigAsync({ logger });
+      expect(() => new ATProtoSDK(configWithLogger)).not.toThrow();
+    });
+
+    it("should work without storage (uses in-memory defaults)", async () => {
+      const config = await createTestConfigAsync();
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { storage, ...configWithoutStorage } = config;
+      // Storage is optional - SDK will use in-memory defaults
+      const sdk = new ATProtoSDK(configWithoutStorage);
+      expect(sdk).toBeInstanceOf(ATProtoSDK);
+    });
+  });
+
+  describe("createATProtoSDK factory", () => {
+    it("should create SDK instance", () => {
+      const sdk = createATProtoSDK(config);
+      expect(sdk).toBeInstanceOf(ATProtoSDK);
+    });
+
+    it("should be equivalent to constructor", () => {
+      const sdk1 = new ATProtoSDK(config);
+      const sdk2 = createATProtoSDK(config);
+      expect(sdk1).toBeInstanceOf(ATProtoSDK);
+      expect(sdk2).toBeInstanceOf(ATProtoSDK);
+    });
+  });
+
+  describe("authorize", () => {
+    it("should throw ValidationError for empty identifier", async () => {
+      const sdk = new ATProtoSDK(config);
+      await expect(sdk.authorize("")).rejects.toThrow(ValidationError);
+      await expect(sdk.authorize("   ")).rejects.toThrow(ValidationError);
+    });
+
+    it("should trim identifier", async () => {
+      const sdk = new ATProtoSDK(config);
+      // Will fail due to network, but should not throw ValidationError
+      await expect(sdk.authorize("  test.bsky.social  ")).rejects.not.toThrow(ValidationError);
+    });
+  });
+
+  describe("restoreSession", () => {
+    it("should throw ValidationError for empty DID", async () => {
+      const sdk = new ATProtoSDK(config);
+      await expect(sdk.restoreSession("")).rejects.toThrow(ValidationError);
+      await expect(sdk.restoreSession("   ")).rejects.toThrow(ValidationError);
+    });
+
+    it("should handle non-existent session", async () => {
+      const sdk = new ATProtoSDK(config);
+      // Use valid DID format - will fail due to network but tests error handling
+      const validDid = "did:plc:abcdefghijklmnopqrstuvwxyz123456";
+      // This will fail due to network/DID validation
+      await expect(sdk.restoreSession(validDid)).rejects.toThrow();
+    });
+  });
+
+  describe("revokeSession", () => {
+    it("should throw ValidationError for empty DID", async () => {
+      const sdk = new ATProtoSDK(config);
+      await expect(sdk.revokeSession("")).rejects.toThrow(ValidationError);
+      await expect(sdk.revokeSession("   ")).rejects.toThrow(ValidationError);
+    });
+  });
+
+  describe("repository", () => {
+    it("should throw ValidationError when session is null", () => {
+      const sdk = new ATProtoSDK(config);
+      expect(() => sdk.repository(null as any)).toThrow(ValidationError);
+    });
+
+    it("should throw ValidationError when PDS not configured and no server specified", async () => {
+      const configWithoutServers = await createTestConfigAsync();
+      delete configWithoutServers.servers;
+      const sdk = new ATProtoSDK(configWithoutServers);
+      const mockSession = { did: "did:plc:test", sub: "did:plc:test", fetchHandler: async () => new Response() } as any;
+      expect(() => sdk.repository(mockSession)).toThrow(ValidationError);
+    });
+
+    it("should throw ValidationError when SDS not configured and server=sds", async () => {
+      const configWithOnlyPds = await createTestConfigAsync();
+      configWithOnlyPds.servers = { pds: "https://pds.example.com" };
+      const sdk = new ATProtoSDK(configWithOnlyPds);
+      const mockSession = { did: "did:plc:test", sub: "did:plc:test", fetchHandler: async () => new Response() } as any;
+      expect(() => sdk.repository(mockSession, { server: "sds" })).toThrow(ValidationError);
+    });
+
+    it("should create repository with custom serverUrl", () => {
+      const sdk = new ATProtoSDK(config);
+      const mockSession = { did: "did:plc:test", sub: "did:plc:test", fetchHandler: async () => new Response() } as any;
+      const repo = sdk.repository(mockSession, { serverUrl: "https://custom.server.com" });
+      expect(repo).toBeDefined();
+      expect(repo.getServerUrl()).toBe("https://custom.server.com");
+    });
+  });
+
+  describe("setup examples", () => {
+    it("should work with minimal config (no storage provided)", async () => {
+      const minimalConfig = await createTestConfigAsync();
+      // Remove storage to test default in-memory implementation
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { storage, ...configWithoutStorage } = minimalConfig;
+      // Storage is optional - SDK will use in-memory defaults
+      const sdk = createATProtoSDK(configWithoutStorage);
+      expect(sdk).toBeInstanceOf(ATProtoSDK);
+    });
+
+    it("should work with all optional fields", async () => {
+      const { InMemoryCache, MockLogger } = await import("../utils/mocks.js");
+      const fullConfig = await createTestConfigAsync({
+        cache: new InMemoryCache(),
+        logger: new MockLogger(),
+        timeouts: {
+          pdsMetadata: 60000,
+          apiRequests: 45000,
+        },
+      });
+      const sdk = createATProtoSDK(fullConfig);
+      expect(sdk).toBeInstanceOf(ATProtoSDK);
+    });
+
+    it("should work with custom storage implementations", async () => {
+      const customConfig = await createTestConfigAsync({
+        storage: {
+          sessionStore: new InMemorySessionStore(),
+          stateStore: new InMemoryStateStore(),
+        },
+      });
+      const sdk = createATProtoSDK(customConfig);
+      expect(sdk).toBeInstanceOf(ATProtoSDK);
+    });
+  });
+});

package/tests/core/errors.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import {
+  ATProtoSDKError,
+  AuthenticationError,
+  SessionExpiredError,
+  ValidationError,
+  NetworkError,
+  SDSRequiredError,
+} from "../../src/core/errors.js";
+
+describe("ATProtoSDKError", () => {
+  it("should create error with message and code", () => {
+    const error = new ATProtoSDKError("Test error", "TEST_ERROR", 500);
+    expect(error.message).toBe("Test error");
+    expect(error.code).toBe("TEST_ERROR");
+    expect(error.status).toBe(500);
+    expect(error.name).toBe("ATProtoSDKError");
+  });
+
+  it("should include cause if provided", () => {
+    const cause = new Error("Original error");
+    const error = new ATProtoSDKError("Test error", "TEST_ERROR", 500, cause);
+    expect(error.cause).toBe(cause);
+  });
+});
+
+describe("AuthenticationError", () => {
+  it("should create authentication error with 401 status", () => {
+    const error = new AuthenticationError("Auth failed");
+    expect(error.message).toBe("Auth failed");
+    expect(error.code).toBe("AUTHENTICATION_ERROR");
+    expect(error.status).toBe(401);
+    expect(error.name).toBe("AuthenticationError");
+  });
+});
+
+describe("SessionExpiredError", () => {
+  it("should create session expired error with default message", () => {
+    const error = new SessionExpiredError();
+    expect(error.message).toBe("Session expired");
+    expect(error.code).toBe("SESSION_EXPIRED");
+    expect(error.status).toBe(401);
+  });
+
+  it("should accept custom message", () => {
+    const error = new SessionExpiredError("Custom message");
+    expect(error.message).toBe("Custom message");
+  });
+});
+
+describe("ValidationError", () => {
+  it("should create validation error with 400 status", () => {
+    const error = new ValidationError("Invalid input");
+    expect(error.message).toBe("Invalid input");
+    expect(error.code).toBe("VALIDATION_ERROR");
+    expect(error.status).toBe(400);
+  });
+});
+
+describe("NetworkError", () => {
+  it("should create network error with 503 status", () => {
+    const error = new NetworkError("Network failure");
+    expect(error.message).toBe("Network failure");
+    expect(error.code).toBe("NETWORK_ERROR");
+    expect(error.status).toBe(503);
+  });
+});
+
+describe("SDSRequiredError", () => {
+  it("should create SDS required error with default message", () => {
+    const error = new SDSRequiredError();
+    expect(error.message).toBe("This operation requires a Shared Data Server (SDS)");
+    expect(error.code).toBe("SDS_REQUIRED");
+    expect(error.status).toBe(400);
+  });
+
+  it("should accept custom message", () => {
+    const error = new SDSRequiredError("Custom SDS error");
+    expect(error.message).toBe("Custom SDS error");
+  });
+});

package/tests/repository/BlobOperationsImpl.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { BlobOperationsImpl } from "../../src/repository/BlobOperationsImpl.js";
+import { NetworkError } from "../../src/core/errors.js";
+
+describe("BlobOperationsImpl", () => {
+  let mockAgent: any;
+  let blobOps: BlobOperationsImpl;
+  const repoDid = "did:plc:testdid123";
+  const serverUrl = "https://pds.example.com";
+
+  beforeEach(() => {
+    mockAgent = {
+      com: {
+        atproto: {
+          repo: {
+            uploadBlob: vi.fn(),
+          },
+          sync: {
+            getBlob: vi.fn(),
+          },
+        },
+      },
+    };
+
+    blobOps = new BlobOperationsImpl(mockAgent, repoDid, serverUrl);
+  });
+
+  describe("upload", () => {
+    it("should upload a blob successfully", async () => {
+      const mockBlob = new Blob(["test content"], { type: "text/plain" });
+      mockAgent.com.atproto.repo.uploadBlob.mockResolvedValue({
+        success: true,
+        data: {
+          blob: {
+            ref: { $link: "bafyrei123" },
+            mimeType: "text/plain",
+            size: 12,
+          },
+        },
+      });
+
+      const result = await blobOps.upload(mockBlob);
+
+      expect(result.ref).toEqual({ $link: "bafyrei123" });
+      expect(result.mimeType).toBe("text/plain");
+      expect(result.size).toBe(12);
+    });
+
+    it("should use blob type as encoding", async () => {
+      const mockBlob = new Blob(["image data"], { type: "image/png" });
+      mockAgent.com.atproto.repo.uploadBlob.mockResolvedValue({
+        success: true,
+        data: {
+          blob: {
+            ref: { $link: "bafyrei123" },
+            mimeType: "image/png",
+            size: 100,
+          },
+        },
+      });
+
+      await blobOps.upload(mockBlob);
+
+      expect(mockAgent.com.atproto.repo.uploadBlob).toHaveBeenCalledWith(
+        expect.any(Uint8Array),
+        { encoding: "image/png" },
+      );
+    });
+
+    it("should default to application/octet-stream for blobs without type", async () => {
+      const mockBlob = new Blob(["data"]);
+      mockAgent.com.atproto.repo.uploadBlob.mockResolvedValue({
+        success: true,
+        data: {
+          blob: {
+            ref: { $link: "bafyrei123" },
+            mimeType: "application/octet-stream",
+            size: 4,
+          },
+        },
+      });
+
+      await blobOps.upload(mockBlob);
+
+      expect(mockAgent.com.atproto.repo.uploadBlob).toHaveBeenCalledWith(
+        expect.any(Uint8Array),
+        { encoding: "application/octet-stream" },
+      );
+    });
+
+    it("should throw NetworkError when API returns success: false", async () => {
+      const mockBlob = new Blob(["test"]);
+      mockAgent.com.atproto.repo.uploadBlob.mockResolvedValue({
+        success: false,
+      });
+
+      await expect(blobOps.upload(mockBlob)).rejects.toThrow(NetworkError);
+    });
+
+    it("should throw NetworkError when API throws", async () => {
+      const mockBlob = new Blob(["test"]);
+      mockAgent.com.atproto.repo.uploadBlob.mockRejectedValue(new Error("Upload failed"));
+
+      await expect(blobOps.upload(mockBlob)).rejects.toThrow(NetworkError);
+    });
+  });
+
+  describe("get", () => {
+    it("should get a blob successfully", async () => {
+      const mockData = new Uint8Array([1, 2, 3, 4]);
+      mockAgent.com.atproto.sync.getBlob.mockResolvedValue({
+        success: true,
+        data: mockData,
+        headers: { "content-type": "image/png" },
+      });
+
+      const result = await blobOps.get("bafyrei123");
+
+      expect(result.data).toEqual(mockData);
+      expect(result.mimeType).toBe("image/png");
+      expect(mockAgent.com.atproto.sync.getBlob).toHaveBeenCalledWith({
+        did: repoDid,
+        cid: "bafyrei123",
+      });
+    });
+
+    it("should default to application/octet-stream if no content-type header", async () => {
+      const mockData = new Uint8Array([1, 2, 3]);
+      mockAgent.com.atproto.sync.getBlob.mockResolvedValue({
+        success: true,
+        data: mockData,
+        headers: {},
+      });
+
+      const result = await blobOps.get("bafyrei123");
+
+      expect(result.mimeType).toBe("application/octet-stream");
+    });
+
+    it("should throw NetworkError when API returns success: false", async () => {
+      mockAgent.com.atproto.sync.getBlob.mockResolvedValue({
+        success: false,
+      });
+
+      await expect(blobOps.get("bafyrei123")).rejects.toThrow(NetworkError);
+    });
+
+    it("should throw NetworkError when API throws", async () => {
+      mockAgent.com.atproto.sync.getBlob.mockRejectedValue(new Error("Blob not found"));
+
+      await expect(blobOps.get("bafyrei123")).rejects.toThrow(NetworkError);
+    });
+  });
+});