Bluesky/AT Protocol Library for Google Apps Script #

A lightweight and robust library to interact with the Bluesky (AT Protocol) API directly from Google Apps Script.

Features #

• Centralized API Handling: All network calls are routed through a secure, internal fetcher that handles headers, authentication, and error management.
• Session Management: Easy creation and retrieval of AT Protocol sessions.
• Content Creation:
  • Create simple text posts with automatic link faceting.
  • Create posts with embedded records (quotes).
  • Create posts with embedded images (including automatic JPEG dimension extraction).
  • Create posts with external link cards (app.bsky.embed.external) and optional thumbnail blobs.
• Social Interactions:
  • Repost records.
  • Retrieve actor profiles and likes.
  • Search for posts by handle and date range.
• Security: Support for PropertiesService to keep credentials out of the source code.
• Extensible: Ability to set custom PDS (Personal Data Servers).

Project Structure #

• Bluesky.gs: The main library containing all AT Protocol methods.
• Tests.gs: A comprehensive testing suite.
  • Unit Tests: Mocked tests that verify logic without making real network calls. Run via runAllTests().
  • Integration Tests: Real-world tests to verify end-to-end functionality. Run via runIntegrationTests().

Installation #

1. Copy the code from Bluesky.gs into your Google Apps Script project.
2. (Optional) Copy Tests.gs to verify your setup.
3. Configure your credentials in Project Settings > Script Properties:
   • BSKY_USER: Your AT Protocol handle or DID.
   • BSKY_PWD: Your app-specific password.

Quick Start #

function post() {
  const user = PropertiesService.getScriptProperties().getProperty('BSKY_USER');
  const pwd = PropertiesService.getScriptProperties().getProperty('BSKY_PWD');
  
  const session = createSession(user, pwd);
  const story = { 
    title: "Hello from Google Apps Script!", 
    url: "https://example.com" 
  };
  
  createRecord(session, story, "en");
}

Testing #

The library includes a custom mocking framework for UrlFetchApp.

• To run logic-only tests: Execute runAllTests() in Tests.gs.
• To run real API tests: Execute runIntegrationTests() in Tests.gs (ensure credentials are set).