@hasna/connectors 1.3.35 → 1.3.37

package/connectors/bluesky/README.md

@@ -0,0 +1,34 @@
+# @hasna/connect-bluesky
+
+Bluesky / AT Protocol connector. Stateless, raw-`fetch` transport with **zero runtime
+dependencies**.
+
+## Auth
+
+Pass credentials per call — nothing is stored on disk:
+
+```ts
+import { Bluesky } from "@hasna/connect-bluesky";
+
+const bsky = new Bluesky({
+  identifier: "alice.bsky.social", // handle or DID
+  appPassword: "xxxx-xxxx-xxxx-xxxx", // app password, NOT the account password
+  pds: "https://bsky.social", // optional, defaults to bsky.social
+});
+```
+
+## Operations
+
+| Method | AT Protocol endpoint |
+|--------|----------------------|
+| `bsky.me()` | `com.atproto.server.createSession` |
+| `bsky.createPost({ text, replyToUri? })` | `com.atproto.repo.createRecord` (`app.bsky.feed.post`) |
+| `bsky.deletePost(uri)` | `com.atproto.repo.deleteRecord` |
+| `bsky.uploadBlob(buffer, mimeType)` | `com.atproto.repo.uploadBlob` |
+| `bsky.listNotifications()` | `app.bsky.notification.listNotifications` |
+| `bsky.getPosts(uris)` | `app.bsky.feed.getPosts` |
+
+Threads: `createPost` with `replyToUri` resolves the parent strong-ref and the thread
+root automatically (deep threads stay correctly rooted).
+
+This connector is consumed by the stateless `@hasna/connectors/social` transport SDK.

package/connectors/bluesky/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hasna/connect-bluesky",
+  "version": "0.1.0",
+  "description": "Bluesky / AT Protocol connector - posts, threads, mentions",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "bluesky",
+    "atproto",
+    "at-protocol",
+    "social",
+    "connector",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}

package/connectors/bluesky/src/api/client.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Bluesky, parseAtUri } from "./index";
+
+const realFetch = globalThis.fetch;
+
+interface Recorded {
+  url: string;
+  method: string;
+  body?: unknown;
+}
+
+function installFetch(handler: (url: string, init: RequestInit | undefined, recorded: Recorded[]) => unknown) {
+  const recorded: Recorded[] = [];
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    recorded.push({ url, method: init?.method ?? "GET", body: init?.body });
+    const json = handler(url, init, recorded);
+    return {
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      async text() {
+        return JSON.stringify(json ?? {});
+      },
+    } as Response;
+  }) as typeof fetch;
+  return recorded;
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe("Bluesky AT Protocol transport", () => {
+  test("parseAtUri splits repo/collection/rkey", () => {
+    expect(parseAtUri("at://did:plc:abc/app.bsky.feed.post/xyz")).toEqual({
+      repo: "did:plc:abc",
+      collection: "app.bsky.feed.post",
+      rkey: "xyz",
+    });
+  });
+
+  test("me() creates a session via com.atproto.server.createSession", async () => {
+    const recorded = installFetch((url) => {
+      if (url.includes("createSession")) return { accessJwt: "a", refreshJwt: "r", did: "did:plc:me", handle: "me.bsky.social" };
+      return {};
+    });
+    const bsky = new Bluesky({ identifier: "me.bsky.social", appPassword: "pw" });
+    const session = await bsky.me();
+    expect(session.did).toBe("did:plc:me");
+    expect(recorded[0].url).toContain("/xrpc/com.atproto.server.createSession");
+    expect(recorded[0].method).toBe("POST");
+  });
+
+  test("createPost (top-level) calls createRecord with app.bsky.feed.post", async () => {
+    const recorded = installFetch((url) => {
+      if (url.includes("createSession")) return { accessJwt: "a", refreshJwt: "r", did: "did:plc:me", handle: "me.bsky.social" };
+      if (url.includes("createRecord")) return { uri: "at://did:plc:me/app.bsky.feed.post/new", cid: "cidnew" };
+      return {};
+    });
+    const bsky = new Bluesky({ identifier: "me.bsky.social", appPassword: "pw" });
+    const res = await bsky.createPost({ text: "hello", createdAt: "2026-01-01T00:00:00Z" });
+    expect(res).toEqual({ uri: "at://did:plc:me/app.bsky.feed.post/new", cid: "cidnew" });
+    const createCall = recorded.find((r) => r.url.includes("createRecord"))!;
+    const body = JSON.parse(createCall.body as string);
+    expect(body.collection).toBe("app.bsky.feed.post");
+    expect(body.repo).toBe("did:plc:me");
+    expect(body.record.text).toBe("hello");
+    expect(body.record.reply).toBeUndefined();
+  });
+
+  test("createPost reply chains parent + thread root strong-refs", async () => {
+    const parentUri = "at://did:plc:other/app.bsky.feed.post/parent";
+    const rootRef = { uri: "at://did:plc:other/app.bsky.feed.post/root", cid: "rootcid" };
+    const recorded = installFetch((url) => {
+      if (url.includes("createSession")) return { accessJwt: "a", refreshJwt: "r", did: "did:plc:me", handle: "me.bsky.social" };
+      if (url.includes("getPosts")) {
+        return { posts: [{ uri: parentUri, cid: "parentcid", record: { reply: { root: rootRef } } }] };
+      }
+      if (url.includes("createRecord")) return { uri: "at://did:plc:me/app.bsky.feed.post/reply", cid: "replycid" };
+      return {};
+    });
+    const bsky = new Bluesky({ identifier: "me.bsky.social", appPassword: "pw" });
+    await bsky.createPost({ text: "reply", replyToUri: parentUri });
+
+    const createCall = recorded.find((r) => r.url.includes("createRecord"))!;
+    const body = JSON.parse(createCall.body as string);
+    expect(body.record.reply.parent).toEqual({ uri: parentUri, cid: "parentcid" });
+    expect(body.record.reply.root).toEqual(rootRef);
+  });
+
+  test("createPost reply uses parent as root for a top-level parent", async () => {
+    const parentUri = "at://did:plc:other/app.bsky.feed.post/top";
+    const recorded = installFetch((url) => {
+      if (url.includes("createSession")) return { accessJwt: "a", refreshJwt: "r", did: "did:plc:me", handle: "me.bsky.social" };
+      if (url.includes("getPosts")) return { posts: [{ uri: parentUri, cid: "topcid" }] };
+      if (url.includes("createRecord")) return { uri: "at://did:plc:me/app.bsky.feed.post/reply", cid: "rc" };
+      return {};
+    });
+    const bsky = new Bluesky({ identifier: "me.bsky.social", appPassword: "pw" });
+    await bsky.createPost({ text: "reply", replyToUri: parentUri });
+    const body = JSON.parse(recorded.find((r) => r.url.includes("createRecord"))!.body as string);
+    expect(body.record.reply.parent).toEqual({ uri: parentUri, cid: "topcid" });
+    expect(body.record.reply.root).toEqual({ uri: parentUri, cid: "topcid" });
+  });
+
+  test("deletePost parses the uri and calls deleteRecord", async () => {
+    const recorded = installFetch((url) => {
+      if (url.includes("createSession")) return { accessJwt: "a", refreshJwt: "r", did: "did:plc:me", handle: "me.bsky.social" };
+      return {};
+    });
+    const bsky = new Bluesky({ identifier: "me.bsky.social", appPassword: "pw" });
+    await bsky.deletePost("at://did:plc:me/app.bsky.feed.post/gone");
+    const del = recorded.find((r) => r.url.includes("deleteRecord"))!;
+    const body = JSON.parse(del.body as string);
+    expect(body).toEqual({ repo: "did:plc:me", collection: "app.bsky.feed.post", rkey: "gone" });
+  });
+
+  test("requires identifier + appPassword", () => {
+    expect(() => new Bluesky({ identifier: "", appPassword: "" })).toThrow();
+  });
+});

package/connectors/bluesky/src/api/client.ts

@@ -0,0 +1,194 @@
+import {
+  BlueskyApiError,
+  type AtUriRef,
+  type BlueskyConfig,
+  type BlueskySession,
+  type CreateRecordResult,
+} from "../types/index";
+
+const DEFAULT_PDS = "https://bsky.social";
+
+/**
+ * Minimal AT Protocol (Bluesky) transport — raw fetch, zero dependencies, no fs.
+ *
+ * Credentials are passed in per construction; the session is created lazily on the
+ * first authenticated call (com.atproto.server.createSession). Nothing is persisted.
+ */
+export class BlueskyClient {
+  private readonly identifier: string;
+  private readonly appPassword: string;
+  private readonly pds: string;
+  private session?: BlueskySession;
+
+  constructor(config: BlueskyConfig) {
+    if (!config?.identifier || !config?.appPassword) {
+      throw new Error("bluesky credentials require `identifier` and `appPassword`");
+    }
+    this.identifier = config.identifier;
+    this.appPassword = config.appPassword;
+    this.pds = (config.pds || DEFAULT_PDS).replace(/\/+$/, "");
+  }
+
+  private async xrpc<T>(
+    nsid: string,
+    options: {
+      method?: "GET" | "POST";
+      params?: Record<string, string | number | undefined>;
+      body?: unknown;
+      auth?: boolean;
+      contentType?: string;
+      rawBody?: BodyInit;
+    } = {},
+  ): Promise<T> {
+    const { method = "GET", params, body, auth = true, contentType, rawBody } = options;
+
+    const url = new URL(`${this.pds}/xrpc/${nsid}`);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null && v !== "") url.searchParams.append(k, String(v));
+      }
+    }
+
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (auth) {
+      const session = await this.ensureSession();
+      headers.Authorization = `Bearer ${session.accessJwt}`;
+    }
+
+    const init: RequestInit = { method, headers };
+    if (rawBody !== undefined) {
+      headers["Content-Type"] = contentType || "application/octet-stream";
+      init.body = rawBody;
+    } else if (body !== undefined && method !== "GET") {
+      headers["Content-Type"] = contentType || "application/json";
+      init.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url.toString(), init);
+
+    if (response.status === 204) return {} as T;
+
+    let data: unknown;
+    const text = await response.text();
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+
+    if (!response.ok) {
+      const errBody = (typeof data === "object" && data !== null ? data : {}) as {
+        error?: string;
+        message?: string;
+      };
+      const message = errBody.message || errBody.error || response.statusText || "Request failed";
+      throw new BlueskyApiError(message, response.status, errBody.error);
+    }
+
+    return data as T;
+  }
+
+  /** Create (or return cached) a session via com.atproto.server.createSession. */
+  async ensureSession(): Promise<BlueskySession> {
+    if (this.session) return this.session;
+    const session = await this.xrpc<BlueskySession>("com.atproto.server.createSession", {
+      method: "POST",
+      auth: false,
+      body: { identifier: this.identifier, password: this.appPassword },
+    });
+    this.session = session;
+    return session;
+  }
+
+  /** Create a record in the authenticated user's repo. */
+  async createRecord(collection: string, record: Record<string, unknown>): Promise<CreateRecordResult> {
+    const session = await this.ensureSession();
+    return this.xrpc<CreateRecordResult>("com.atproto.repo.createRecord", {
+      method: "POST",
+      body: { repo: session.did, collection, record },
+    });
+  }
+
+  /** Delete a record by its at:// URI (parses repo/collection/rkey). */
+  async deleteRecord(uri: string): Promise<void> {
+    const session = await this.ensureSession();
+    const parsed = parseAtUri(uri);
+    await this.xrpc("com.atproto.repo.deleteRecord", {
+      method: "POST",
+      body: { repo: session.did, collection: parsed.collection, rkey: parsed.rkey },
+    });
+  }
+
+  /** Upload a blob (image/video) — returns the blob ref for embedding. */
+  async uploadBlob(data: Buffer | Uint8Array, mimeType: string): Promise<{ blob: unknown }> {
+    return this.xrpc<{ blob: unknown }>("com.atproto.repo.uploadBlob", {
+      method: "POST",
+      rawBody: data as unknown as BodyInit,
+      contentType: mimeType || "application/octet-stream",
+    });
+  }
+
+  /** List notifications (used for mentions). */
+  async listNotifications(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    notifications: Array<{
+      uri: string;
+      cid: string;
+      reason: string;
+      indexedAt?: string;
+      author?: { did: string; handle: string };
+      record?: { text?: string; createdAt?: string };
+    }>;
+    cursor?: string;
+  }> {
+    return this.xrpc("app.bsky.notification.listNotifications", {
+      method: "GET",
+      params: { limit: options?.limit, cursor: options?.cursor },
+    });
+  }
+
+  /** Fetch hydrated posts by URI (used for analytics/metrics + reply refs). */
+  async getPosts(uris: string[]): Promise<{
+    posts: Array<{
+      uri: string;
+      cid?: string;
+      likeCount?: number;
+      repostCount?: number;
+      replyCount?: number;
+      quoteCount?: number;
+      record?: { reply?: { root?: { uri: string; cid: string } } };
+    }>;
+  }> {
+    const url = new URL(`${this.pds}/xrpc/app.bsky.feed.getPosts`);
+    for (const u of uris) url.searchParams.append("uris", u);
+    const session = await this.ensureSession();
+    const response = await fetch(url.toString(), {
+      headers: { Accept: "application/json", Authorization: `Bearer ${session.accessJwt}` },
+    });
+    const text = await response.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      throw new BlueskyApiError(data?.message || data?.error || response.statusText, response.status, data?.error);
+    }
+    return data;
+  }
+
+  getSession(): BlueskySession | undefined {
+    return this.session;
+  }
+}
+
+/** Parse an at:// URI into its components. */
+export function parseAtUri(uri: string): { repo: string; collection: string; rkey: string } {
+  const match = /^at:\/\/([^/]+)\/([^/]+)\/(.+)$/.exec(uri);
+  if (!match) {
+    throw new Error(`Invalid at:// URI: ${uri}`);
+  }
+  return { repo: match[1]!, collection: match[2]!, rkey: match[3]! };
+}
+
+export type { AtUriRef };

package/connectors/bluesky/src/api/index.ts

@@ -0,0 +1,108 @@
+import { BlueskyClient, parseAtUri } from "./client";
+import type { BlueskyConfig, BlueskySession, CreateRecordResult } from "../types/index";
+
+const POST_COLLECTION = "app.bsky.feed.post";
+
+export interface CreatePostOptions {
+  text: string;
+  /** at:// URI of the post being replied to (the social SDK passes the parent uri). */
+  replyToUri?: string;
+  /** Optional embed (e.g. images) built by the caller. */
+  embed?: Record<string, unknown>;
+  createdAt?: string;
+}
+
+/**
+ * Main Bluesky (AT Protocol) connector class.
+ */
+export class Bluesky {
+  private readonly client: BlueskyClient;
+
+  constructor(config: BlueskyConfig) {
+    this.client = new BlueskyClient(config);
+  }
+
+  static fromEnv(): Bluesky {
+    const identifier = process.env.BLUESKY_IDENTIFIER;
+    const appPassword = process.env.BLUESKY_APP_PASSWORD;
+    const pds = process.env.BLUESKY_PDS;
+    if (!identifier || !appPassword) {
+      throw new Error("BLUESKY_IDENTIFIER and BLUESKY_APP_PASSWORD environment variables are required");
+    }
+    return new Bluesky({ identifier, appPassword, pds });
+  }
+
+  /** Resolve the authenticated account (did + handle). */
+  async me(): Promise<BlueskySession> {
+    return this.client.ensureSession();
+  }
+
+  /**
+   * Create a feed post. For replies, we resolve the root of the thread so the
+   * reply ref carries both parent and root strong-refs (AT Protocol requirement).
+   */
+  async createPost(options: CreatePostOptions): Promise<CreateRecordResult> {
+    const record: Record<string, unknown> = {
+      $type: POST_COLLECTION,
+      text: options.text,
+      createdAt: options.createdAt || new Date().toISOString(),
+    };
+
+    if (options.embed) {
+      record.embed = options.embed;
+    }
+
+    if (options.replyToUri) {
+      const { parent, root } = await this.resolveReplyRefs(options.replyToUri);
+      record.reply = { root, parent };
+    }
+
+    return this.client.createRecord(POST_COLLECTION, record);
+  }
+
+  async deletePost(uri: string): Promise<void> {
+    return this.client.deleteRecord(uri);
+  }
+
+  /** Upload an image/video blob and return a strong blob ref. */
+  async uploadBlob(data: Buffer | Uint8Array, mimeType: string): Promise<unknown> {
+    const res = await this.client.uploadBlob(data, mimeType);
+    return res.blob;
+  }
+
+  async listNotifications(options?: { limit?: number; cursor?: string }) {
+    return this.client.listNotifications(options);
+  }
+
+  async getPosts(uris: string[]) {
+    return this.client.getPosts(uris);
+  }
+
+  getClient(): BlueskyClient {
+    return this.client;
+  }
+
+  /**
+   * Resolve the strong-refs needed for a reply: the parent ref ({uri,cid}) and the
+   * thread root. If the parent is itself a reply, its record carries the thread
+   * root; otherwise the parent IS the root. This keeps deep threads correctly
+   * rooted per the AT Protocol app.bsky.feed.post reply schema.
+   */
+  private async resolveReplyRefs(parentUri: string): Promise<{
+    parent: { uri: string; cid: string };
+    root: { uri: string; cid: string };
+  }> {
+    parseAtUri(parentUri);
+    const posts = await this.client.getPosts([parentUri]);
+    const match = posts.posts.find((p) => p.uri === parentUri);
+    if (!match || !match.cid) {
+      throw new Error(`Cannot resolve parent post for reply: ${parentUri}`);
+    }
+    const parent = { uri: match.uri, cid: match.cid };
+    const root = match.record?.reply?.root ?? parent;
+    return { parent, root };
+  }
+}
+
+export { BlueskyClient, parseAtUri } from "./client";
+export type { BlueskyConfig, BlueskySession, CreateRecordResult } from "../types/index";

package/connectors/bluesky/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @hasna/connect-bluesky
+ *
+ * Bluesky / AT Protocol connector. Stateless, raw-fetch transport with zero
+ * runtime dependencies — login via com.atproto.server.createSession, post via
+ * com.atproto.repo.createRecord (app.bsky.feed.post), delete via
+ * com.atproto.repo.deleteRecord.
+ */
+export { Bluesky, BlueskyClient, parseAtUri } from "./api/index";
+export {
+  BlueskyApiError,
+  type BlueskyConfig,
+  type BlueskySession,
+  type CreateRecordResult,
+  type AtUriRef,
+} from "./types/index";
+export type { CreatePostOptions } from "./api/index";

package/connectors/bluesky/src/types/index.ts

@@ -0,0 +1,46 @@
+// Bluesky / AT Protocol types
+
+export interface BlueskyConfig {
+  /** Handle or DID, e.g. "alice.bsky.social" */
+  identifier: string;
+  /** App password (NOT the account password) */
+  appPassword: string;
+  /** Personal Data Server base URL. Defaults to https://bsky.social */
+  pds?: string;
+}
+
+export interface BlueskySession {
+  accessJwt: string;
+  refreshJwt: string;
+  handle: string;
+  did: string;
+  email?: string;
+}
+
+/** A strong-ref to an AT Protocol record (used for reply roots/parents). */
+export interface AtUriRef {
+  uri: string;
+  cid: string;
+}
+
+export interface CreateRecordResult {
+  uri: string;
+  cid: string;
+}
+
+export interface BlueskyApiErrorBody {
+  error?: string;
+  message?: string;
+}
+
+export class BlueskyApiError extends Error {
+  public readonly statusCode: number;
+  public readonly errorCode?: string;
+
+  constructor(message: string, statusCode: number, errorCode?: string) {
+    super(message);
+    this.name = "BlueskyApiError";
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+  }
+}

package/connectors/bluesky/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/x/src/api/media.ts

@@ -3,8 +3,6 @@
  * Uses OAuth 1.0a for authentication
  */
 
-import { readFileSync, statSync } from 'fs';
-import { basename } from 'path';
 import { OAuth1Client } from './oauth1';
 
 const UPLOAD_URL = 'https://upload.twitter.com/1.1/media/upload.json';
@@ -243,8 +241,11 @@ export class MediaApi {
     filePath: string,
     options: MediaUploadOptions = {}
   ): Promise<MediaUploadResult> {
+    // Lazy-load node:fs so this module stays bundle-safe (free of static fs
+    // imports) for consumers that only ever call uploadBuffer (e.g. the
+    // stateless @hasna/connectors/social entry point).
+    const { readFileSync } = await import('node:fs');
     const fileData = readFileSync(filePath);
-    const fileSize = statSync(filePath).size;
     const mimeType = getMimeType(filePath);
 
     return this.uploadBuffer(fileData, mimeType, {