universal-social-sdk 1.0.1 → 1.1.1

package/.env.example

@@ -59,3 +59,14 @@ SOCIAL_SDK_MAX_RETRIES=3
 SOCIAL_SDK_RETRY_BASE_MS=500
 OLLAMA_HOST=http://127.0.0.1:11434
 OLLAMA_MODEL=llama3.2:3b
+UPDATER_LLM_PROVIDER=openrouter
+UPDATER_LLM_BASE_URL=https://openrouter.ai/api/v1
+UPDATER_LLM_API_KEY=
+UPDATER_LLM_MODEL=google/gemma-3-4b-it:free
+UPDATER_LLM_APP_NAME=universal-social-sdk-updater
+UPDATER_LLM_APP_URL=https://github.com/Gabo-Tech/universal-social-sdk
+UPDATER_LLM_MAX_TOKENS=1200
+UPDATER_LLM_MAX_DOC_CHARS_PER_PAGE=6000
+UPDATER_LLM_MAX_ENDPOINT_ROWS_PER_PAGE=40
+UPDATER_LLM_MAX_MODEL_ATTEMPTS=4
+UPDATER_LLM_FALLBACK_MODELS=google/gemma-3-4b-it:free,qwen/qwen3-4b:free,openai/gpt-oss-20b:free

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+### Added
+
+- Non-interactive updater mode for CI/automation (`--ci`, `--open-pr`, `--branch-prefix`, `--base`, `--artifacts-dir`).
+- Structured updater artifacts (`.artifacts/update-plan.json`, `.artifacts/update-diff-summary.json`, `.artifacts/pr-title.txt`, `.artifacts/pr-body.md`).
+- Strict Ollama patch-plan schema validation with typed `changes` metadata (platform, endpoint, change type, confidence).
+- Updater LLM provider abstraction with OpenRouter support (`UPDATER_LLM_*`, `OPENROUTER_*`) while keeping legacy Ollama compatibility.
+- Scheduled PR automation workflow: `.github/workflows/auto-update-pr.yml`.
+- Workflow-dispatch `dry_run` mode for updater automation (detect and generate artifacts without opening PRs).
+- Unit tests covering updater plan validation and no-change detection behavior.
+
+### Changed
+
+- Updater CI mode now enforces `npm run build` and `npm run test:unit` before PR automation proceeds.
+- Auto-update PR workflow now excludes `.artifacts/*` from commits while still using artifacts for PR metadata.
+
+## [1.1.0] - 2026-03-08
+
+### Added
+
+- `src/webhooks` module with:
+  - Meta and X signature verification helpers
+  - normalized webhook event parsing helpers
+  - `WebhookRouter` for typed and wildcard event dispatch
+- Unit tests for webhook verification, normalization, and routing.
+- `src/queue` module with:
+  - `QueueAdapter` interface
+  - `InMemoryQueueAdapter`
+  - skeleton adapters for BullMQ and SQS
+  - queue adapter registry (`setQueueAdapter`, `getQueueAdapter`, `resetQueueAdapter`)
+- Scheduler integration to route scheduled jobs through the active queue adapter.
+- Unit tests for queue adapter registry and scheduler behavior.
+- Added typed response interfaces and explicit return contracts across all public platform methods.
+- Refined response contracts with platform-specific action/delete/result aliases for stronger API clarity.
+- Added internal normalized result helpers so action/delete/mutation/detail responses remain stable even if upstream provider payloads drift.
+- Added `docs/RESPONSE_CONTRACTS.md` with stable contract reference and integration guidance.
+- Exported response interfaces from package root.
+- Unit test coverage for typed response shapes.
+
 ## [1.0.1] - 2026-03-08
 
 ### Added

package/README.md

@@ -9,7 +9,9 @@ TypeScript-first, ESM-only, zero-bloat Node.js SDK that provides one unified int
 
 - [Project Structure](./docs/PROJECT_STRUCTURE.md)
 - [NPM Package Guide](./docs/NPM_PACKAGE_GUIDE.md)
+- [Response Contracts](./docs/RESPONSE_CONTRACTS.md)
 - [Contributing](./docs/CONTRIBUTING.md)
+- [Roadmap v1.1.0](./docs/ROADMAP_v1.1.0.md)
 - [Code of Conduct](./CODE_OF_CONDUCT.md)
 - [Security Policy](./SECURITY.md)
 - [Changelog](./CHANGELOG.md)
@@ -55,6 +57,7 @@ Run bundled examples:
 npm run example:x
 npm run example:instagram
 npm run example:bluesky
+npm run example:queue
 ```
 
 Files:
@@ -62,6 +65,60 @@ Files:
 - `examples/x-post.mjs`
 - `examples/instagram-reel.mjs`
 - `examples/bluesky-post.mjs`
+- `examples/queue-in-memory.mjs`
+
+## Queue Adapters
+
+The scheduler uses a queue adapter. By default it uses an in-memory adapter.
+
+```ts
+import { InMemoryQueueAdapter, setQueueAdapter } from "universal-social-sdk";
+
+setQueueAdapter(new InMemoryQueueAdapter());
+```
+
+Adapter exports:
+
+- `InMemoryQueueAdapter` (default behavior)
+- `BullMQAdapter` (skeleton)
+- `SQSAdapter` (skeleton)
+
+The scheduler APIs (for example `X.scheduleTweet`) will use the active adapter automatically.
+
+## Typed Responses
+
+All public SDK methods now return concrete TypeScript interfaces, including platform-specific action/delete aliases for clearer contracts.
+Action/delete/mutation/detail responses are normalized into stable contracts (`success`, `action`/`targetId`/`resourceId`, `raw`) so provider endpoint changes are isolated to SDK internals.
+
+```ts
+import { X } from "universal-social-sdk";
+import type { XPostResult } from "universal-social-sdk";
+
+const result: XPostResult = await X.postTweet({ text: "typed response" });
+console.log(result.data.id);
+```
+
+## Webhooks
+
+The SDK includes webhook utilities for Meta-style and X-style signatures, normalized event parsing, and a lightweight router.
+
+```ts
+import {
+  WebhookRouter,
+  verifyMetaWebhookSignature,
+  verifyXWebhookSignature
+} from "universal-social-sdk";
+
+const router = new WebhookRouter();
+
+router.on("meta.feed", async (event) => {
+  console.log("Meta feed event", event.payload);
+});
+
+router.on("x.tweet_create_events", async (event) => {
+  console.log("X tweet event", event.payload);
+});
+```
 
 ## Required Environment Variables
 
@@ -135,8 +192,19 @@ Files:
 
 - `SOCIAL_SDK_MAX_RETRIES` (default `3`)
 - `SOCIAL_SDK_RETRY_BASE_MS` (default `500`)
-- `OLLAMA_HOST` (default `http://127.0.0.1:11434`)
-- `OLLAMA_MODEL` (default `llama3.2:3b`)
+- `UPDATER_LLM_PROVIDER` (`openrouter` or `ollama`, default `openrouter` when API key is present, otherwise `ollama`)
+- `UPDATER_LLM_BASE_URL` (default `https://openrouter.ai/api/v1`)
+- `UPDATER_LLM_API_KEY` (or `OPENROUTER_API_KEY`)
+- `UPDATER_LLM_MODEL` (or `OPENROUTER_MODEL`, default `google/gemma-3-4b-it:free` for OpenRouter, `llama3.2:3b` for Ollama)
+- `UPDATER_LLM_APP_NAME` (optional request metadata)
+- `UPDATER_LLM_APP_URL` (optional request metadata)
+- `UPDATER_LLM_MAX_TOKENS` (default `1200`)
+- `UPDATER_LLM_MAX_DOC_CHARS_PER_PAGE` (default `6000`)
+- `UPDATER_LLM_MAX_ENDPOINT_ROWS_PER_PAGE` (default `40`)
+- `UPDATER_LLM_MAX_MODEL_ATTEMPTS` (default `4`)
+- `UPDATER_LLM_FALLBACK_MODELS` (comma-separated OpenRouter model IDs used after primary model fails)
+- `OLLAMA_HOST` (legacy local runtime support, default `http://127.0.0.1:11434`)
+- `OLLAMA_MODEL` (legacy local runtime support)
 
 ## CLI
 
@@ -161,17 +229,29 @@ npx universal-social-sdk update
 ```bash
 npx universal-social-sdk update --dry-run
 npx universal-social-sdk update --model llama3.2
+npx universal-social-sdk update --fallback-models "google/gemma-3-4b-it:free,qwen/qwen3-4b:free"
+npx universal-social-sdk update --max-model-attempts 5
 npx universal-social-sdk update --yes
+npx universal-social-sdk update --ci --open-pr --base main --branch-prefix chore/updater
 ```
 
 Flow:
 
 1. Crawls official docs pages for X, Meta Graph API, Instagram Graph API, and LinkedIn.
 2. Extracts clean text and table-like endpoint data with Cheerio.
-3. Sends doc snapshots to your local model runtime.
+3. Sends doc snapshots to your configured LLM provider (OpenRouter or local runtime).
+   - In OpenRouter mode, retries across a fallback model chain for `402/404/408/429` model-level failures with a short backoff between attempts.
 4. Requests generated method updates + full TypeScript file content.
-5. Shows git-style diffs and asks for confirmation.
-6. Applies patches and rebuilds package.
+5. Runs safety checks to reject suspicious placeholder rewrites or destructive class replacements.
+6. Shows git-style diffs and asks for confirmation.
+7. Applies patches and rebuilds package.
+
+CI/PR mode writes deterministic artifacts in `.artifacts/`:
+
+- `update-plan.json`
+- `update-diff-summary.json`
+- `pr-title.txt`
+- `pr-body.md`
 
 ## Supported Methods
 
@@ -313,6 +393,12 @@ This repo includes:
 
 - `.github/workflows/ci.yml` for build + unit tests on every push/PR.
 - `.github/workflows/release.yml` for npm publish on tag (`v*`) or manual dispatch.
+- `.github/workflows/auto-update-pr.yml` for scheduled doc crawling + updater PR generation.
+  - Generates `.artifacts/*` for PR metadata during the run but does not commit artifact files.
+
+Manual dry-run option for updater workflow:
+
+- In **Actions -> Auto Update PR -> Run workflow**, set `dry_run=true` to run detection and artifact generation only (no branch/PR).
 
 Configure these repository secrets to enable integration CI:
 
@@ -344,3 +430,18 @@ Configure these repository secrets to enable integration CI:
 Configure this repository secret for publishing:
 
 - `NPM_TOKEN`
+
+Configure this repository secret for scheduled updater PRs:
+
+- `UPDATER_LLM_PROVIDER` (`openrouter` or `ollama`)
+- `UPDATER_LLM_API_KEY` (required for `openrouter`; or use `OPENROUTER_API_KEY`)
+- `UPDATER_LLM_MODEL` (optional)
+- `UPDATER_LLM_BASE_URL` (optional; defaults to OpenRouter URL)
+- `UPDATER_LLM_MAX_TOKENS` (optional; cap completion size/cost)
+- `UPDATER_LLM_MAX_MODEL_ATTEMPTS` (optional)
+- `UPDATER_LLM_FALLBACK_MODELS` (optional comma-separated model chain)
+
+Alternative OpenRouter-compatible secret names also supported:
+
+- `OPENROUTER_API_KEY`
+- `OPENROUTER_MODEL`