astro-buffer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agustín Díaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# astro-buffer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small Astro integration that shares newly published articles to your connected Buffer channels.
+It uses Buffer's experimental `createContentItem` API: one request per article, with a variant for
+each channel. No SDK, external database, or browser JavaScript.
+
+## Setup
+
+Requires Astro 7.x and Node 24 or newer. Node 24 LTS is the tested baseline.
+
+Install it in your Astro project:
+
+```sh
+npm install astro-buffer
+```
+
+Configure Astro with an endpoint that lists your articles, and the directory containing their
+source files:
+
+```js
+import { defineConfig } from "astro/config";
+import buffer from "astro-buffer";
+
+export default defineConfig({
+  site: "https://example.com",
+  integrations: [
+    buffer({
+      posts: new URL("./src/buffer-posts.ts", import.meta.url),
+      contentDirectory: "src/content/blog",
+      // Optional: omit to use every connected, unlocked channel.
+      channelIds: ["your_linkedin_channel_id", "your_bluesky_channel_id"],
+      // Optional: use Buffer's posting schedule instead of publishing immediately.
+      mode: "addToQueue",
+    }),
+  ],
+});
+```
+
+In `src/buffer-posts.ts`, adapt your content collection and public routes:
+
+```ts
+import type { APIRoute } from "astro";
+import { getCollection } from "astro:content";
+
+export const GET: APIRoute = async ({ site }) => {
+  if (!site) throw new Error("Configure site before publishing.");
+  const posts = await getCollection("blog");
+  return Response.json(
+    posts.map((post) => ({
+      filePath: post.filePath,
+      title: post.data.title,
+      url: new URL(`/${post.id}/`, site).href,
+    })),
+  );
+};
+```
+
+This endpoint is injected only for publishing builds and removed from the output before any API
+requests. It is not injected during normal builds, development, preview, or sync, even if the
+publishing flag is present for those non-build commands.
+
+Each article may also include an optional `text` string in the endpoint response. It replaces
+the title in the announcement, but not the content item's title. For example:
+
+```js
+{
+  filePath: post.filePath,
+  title: post.data.title,
+  url: new URL(`/${post.id}/`, site).href,
+  text: post.data.description,
+}
+```
+
+The integration always appends a blank line and the canonical article URL, preserving duplicate
+detection. Omit `text` to keep the title + URL default. Provided text must be non-empty; surrounding
+whitespace is trimmed. Dry runs show the same announcement text as publishing.
+
+## Publishing
+
+Normal builds and development never publish. Set these environment variables for a publishing build:
+
+| Variable | Purpose |
+| --- | --- |
+| `BUFFER_PUBLISH=true` | Explicitly enable publishing. |
+| `BUFFER_DRY_RUN=true` | Preview announcements without creating posts (also requires `BUFFER_PUBLISH=true`). |
+| `BUFFER_API_KEY` | Buffer personal API key; keep this secret. |
+| `BUFFER_ORGANIZATION_ID` | Organization containing the channels to share to. |
+| `BUFFER_BASE_REF` | Full commit SHA before the newly added articles. |
+
+Create a personal API key in Buffer's **Settings → API**, selecting only `account:read`,
+`posts:read`, and `posts:write`. The integration reads channels, checks post history for duplicates,
+and creates announcements; it does not manage account or channel settings.
+
+Store the key in your CI secret store or an ignored local `.env` file. Load local environment
+variables before running Astro; the integration reads `process.env` and does not load `.env`
+itself. Find your organization ID with Buffer's `account { organizations { id name } }` query
+and use the ID of the organization containing your channels.
+
+Run `astro build` from the exact publishing commit in a Git checkout with the base revision
+available. Only added files between that revision and `HEAD` are shared; edits, detected renames,
+and archive entries are ignored. Directory paths are relative to the Astro project root.
+
+Each article's production URL must return successfully without a redirect. The integration waits
+about five minutes for deployment before failing. Posts use `title + URL` unless custom text is
+provided. The default `mode: "shareNow"` publishes immediately; `mode: "addToQueue"` uses the next
+available slot in each channel's Buffer posting schedule. Both use automatic delivery.
+Disconnected and locked channels are reported and excluded.
+
+The announcement contains no media. Networks requiring media or extra metadata may reject it.
+Batch input validation is all-or-nothing. Subsequent processing errors can occur after Buffer
+creates records; inspect the Buffer dashboard for delivery errors.
+
+On failure, rerun with the same base revision. All history pages are checked for matching article
+URLs per channel before creating anything. Existing failed posts, drafts, or approval requests
+require attention in Buffer, not replacement posts. Keep their URL text and records intact.
+Creation requests are never automatically retried; this is not an exactly-once delivery guarantee.
+Run publishing builds serially to avoid races.
+
+Dry runs still require credentials and a base revision. They read channels and post history,
+report only missing announcements, and skip deployment checks and all Buffer mutations. Existing
+failed posts still require attention and cause the run to fail.
+
+Keep publishing separate from preview/PR builds. A production-only GitHub Actions workflow can
+invoke `BUFFER_PUBLISH=true astro build` after checking out the publishing commit with
+`fetch-depth: 0`. Pass `${{ github.event.before }}` as `BUFFER_BASE_REF` for push events. Serialize
+runs with a concurrency group using `queue: max` so newer pushes do not replace pending runs.
+
+## Development
+
+Use Node 24 or newer. Tests exercise the compiled JavaScript that
+ships to users, not TypeScript source:
+
+```sh
+npm ci
+npm test
+npm run build
+npm run format:check
+```
+
+CI runs the build, tests, and formatting check on Node 24 LTS with Astro 7.
+Buffer requests are mocked; no credentials or real social posts are involved.
+
+References: [Astro Integration API](https://docs.astro.build/en/reference/integrations-reference/)
+and [Buffer content items](https://developers.buffer.com/guides/content-items).

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { AstroIntegration } from "astro";
+export interface BufferOptions {
+    posts: URL;
+    contentDirectory: string;
+    channelIds?: string[];
+    mode?: "shareNow" | "addToQueue";
+}
+export default function buffer({ posts: entrypoint, contentDirectory, channelIds, mode, }: BufferOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,237 @@
+import { execFileSync } from "node:child_process";
+import { readFile, unlink } from "node:fs/promises";
+import timers from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+async function request(token, query, variables) {
+    const response = await fetch("https://api.buffer.com", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query, variables }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) {
+        const retryAfter = response.headers.get("Retry-After");
+        throw new Error(`Buffer request failed: HTTP ${response.status}.${retryAfter ? ` Retry after ${retryAfter} seconds.` : ""}`);
+    }
+    const result = await response.json();
+    if (result.errors?.length) {
+        throw new Error(`Buffer: ${result.errors.map((error) => error.message).join("; ")}`);
+    }
+    if (!result.data) {
+        throw new Error("Buffer returned no data.");
+    }
+    return result.data;
+}
+export default function buffer({ posts: entrypoint, contentDirectory, channelIds, mode = "shareNow", }) {
+    if (mode !== "shareNow" && mode !== "addToQueue") {
+        throw new Error('mode must be "shareNow" or "addToQueue".');
+    }
+    if (channelIds && (!channelIds.length || channelIds.some((id) => !id.trim()))) {
+        throw new Error("channelIds must contain at least one non-empty Buffer channel ID.");
+    }
+    let root;
+    let enabled = false;
+    const dryRun = process.env.BUFFER_DRY_RUN === "true";
+    return {
+        name: "astro-buffer",
+        hooks: {
+            "astro:config:setup": ({ injectRoute, command }) => {
+                enabled = command === "build" && process.env.BUFFER_PUBLISH === "true";
+                if (enabled) {
+                    injectRoute({
+                        pattern: "/buffer-posts.json",
+                        entrypoint: fileURLToPath(entrypoint),
+                        prerender: true,
+                    });
+                }
+            },
+            "astro:config:done": ({ config }) => {
+                root = config.root;
+            },
+            "astro:build:done": async ({ dir, logger }) => {
+                if (!enabled)
+                    return;
+                const manifest = new URL("buffer-posts.json", dir);
+                const articles = JSON.parse(await readFile(manifest, "utf8"));
+                await unlink(manifest);
+                const base = process.env.BUFFER_BASE_REF;
+                if (!base || !/^[a-f0-9]{40}$/i.test(base) || /^0+$/.test(base)) {
+                    throw new Error("Set BUFFER_BASE_REF to the full commit SHA before the new posts.");
+                }
+                const added = new Set(execFileSync("git", [
+                    "diff",
+                    "--name-only",
+                    "--relative",
+                    "-z",
+                    "--diff-filter=A",
+                    "--find-renames",
+                    base,
+                    "HEAD",
+                    "--",
+                    contentDirectory,
+                ], { cwd: fileURLToPath(root), encoding: "utf8" })
+                    .split("\0")
+                    .filter(Boolean));
+                const posts = articles
+                    .filter((article) => added.has(article.filePath))
+                    .map((article) => {
+                    if (article.text !== undefined &&
+                        (typeof article.text !== "string" || !article.text.trim())) {
+                        throw new Error(`"${article.title}": announcement text must be a non-empty string.`);
+                    }
+                    return {
+                        ...article,
+                        text: `${article.text?.trim() ?? article.title}\n\n${article.url}`,
+                    };
+                });
+                if (!posts.length) {
+                    logger.info("No new blog posts to share.");
+                    return;
+                }
+                const token = process.env.BUFFER_API_KEY;
+                const organizationId = process.env.BUFFER_ORGANIZATION_ID;
+                if (!token || !organizationId) {
+                    throw new Error("Set BUFFER_API_KEY and BUFFER_ORGANIZATION_ID before publishing.");
+                }
+                const { channels } = await request(token, `query Channels($input: ChannelsInput!) {
+            channels(input: $input) { id name isDisconnected isLocked }
+          }`, { input: { organizationId } });
+                if (channelIds) {
+                    const unknown = channelIds.filter((id) => !channels.some((channel) => channel.id === id));
+                    if (unknown.length) {
+                        throw new Error(`Unknown Buffer channel IDs: ${unknown.join(", ")}.`);
+                    }
+                }
+                const connected = channels.filter((channel) => {
+                    if (channelIds && !channelIds.includes(channel.id))
+                        return false;
+                    if (channel.isDisconnected || channel.isLocked) {
+                        logger.warn(`Cannot publish to "${channel.name}": disconnected or locked in Buffer.`);
+                        return false;
+                    }
+                    return true;
+                });
+                if (!connected.length) {
+                    throw new Error("No connected, unlocked Buffer channels found.");
+                }
+                const existing = [];
+                let after = null;
+                do {
+                    const { posts: page, } = await request(token, `query Posts($input: PostsInput!, $after: String) {
+              posts(input: $input, first: 100, after: $after) {
+                edges { node { id text channelId status } }
+                pageInfo { hasNextPage endCursor }
+              }
+            }`, {
+                        input: { organizationId, filter: { channelIds: connected.map(({ id }) => id) } },
+                        after,
+                    });
+                    if (!page.edges) {
+                        throw new Error("Buffer returned no post history.");
+                    }
+                    existing.push(...page.edges.map(({ node }) => node));
+                    if (page.pageInfo.hasNextPage &&
+                        (!page.pageInfo.endCursor || page.pageInfo.endCursor === after)) {
+                        throw new Error("Buffer returned an invalid pagination cursor.");
+                    }
+                    after = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
+                } while (after);
+                const failures = [];
+                for (const article of posts) {
+                    const pending = [];
+                    for (const channel of connected) {
+                        const shared = existing.find((post) => post.channelId === channel.id && post.text.split(/\s+/).includes(article.url));
+                        if (shared) {
+                            if (!["sent", "scheduled", "sending"].includes(shared.status)) {
+                                failures.push(new Error(`Review Buffer post ${shared.id} for "${channel.name}": ${shared.status}.`));
+                            }
+                            logger.info(`Already in Buffer: "${article.title}" -> "${channel.name}".`);
+                            continue;
+                        }
+                        pending.push(channel);
+                    }
+                    if (!pending.length)
+                        continue;
+                    if (dryRun) {
+                        logger.info(`Dry run: ${JSON.stringify({
+                            title: article.title,
+                            text: article.text,
+                            channels: pending.map(({ id, name }) => ({ id, name })),
+                            mode,
+                        })}`);
+                        continue;
+                    }
+                    let live = false;
+                    const deadline = Date.now() + 300_000;
+                    while (Date.now() < deadline) {
+                        let response;
+                        try {
+                            response = await fetch(article.url, {
+                                method: "HEAD",
+                                signal: AbortSignal.timeout(10_000),
+                            });
+                        }
+                        catch (error) {
+                            if (!(error instanceof TypeError) &&
+                                !(error instanceof Error && error.name === "TimeoutError")) {
+                                throw error;
+                            }
+                            logger.warn(`Cannot reach ${article.url}: ${error.message}. Retrying.`);
+                        }
+                        if (response) {
+                            if (response.ok && response.url === article.url) {
+                                live = true;
+                                break;
+                            }
+                            if (![404, 502, 503, 504].includes(response.status)) {
+                                throw new Error(`Cannot verify ${article.url}: HTTP ${response.status}.`);
+                            }
+                        }
+                        logger.info(`Waiting for ${article.url} to be deployed...`);
+                        await timers.setTimeout(10_000);
+                    }
+                    if (!live) {
+                        throw new Error(`${article.url} is not live yet. Rerun after deployment succeeds.`);
+                    }
+                    const { createContentItem } = await request(token, `mutation Publish($input: CreateContentItemInput!) {
+              createContentItem(input: $input) {
+                ... on CreateContentItemSuccess { content { id } }
+                ... on CreateContentItemFailure {
+                  message
+                  errors { ... on MutationError { message } }
+                }
+              }
+            }`, {
+                        input: {
+                            organizationId,
+                            title: article.title,
+                            posts: pending.map(({ id }) => ({
+                                channelId: id,
+                                text: article.text,
+                                schedulingType: "automatic",
+                                mode,
+                            })),
+                        },
+                    });
+                    if (!createContentItem.content?.id) {
+                        failures.push(new Error(`"${article.title}": ${[
+                            createContentItem.message ?? "No content item ID returned.",
+                            ...(createContentItem.errors ?? []).map(({ message }) => message),
+                        ].join("; ")}`));
+                        continue;
+                    }
+                    logger.info(`Submitted "${article.title}" to ${pending.length} channels (${createContentItem.content.id}).`);
+                }
+                if (failures.length) {
+                    throw new AggregateError(failures, [
+                        "Some Buffer posts need attention; reruns skip existing posts.",
+                        ...failures.map((error) => error.message),
+                    ].join("\n"));
+                }
+            },
+        },
+    };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "astro-buffer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Share newly published Astro articles through Buffer.",
+  "license": "MIT",
+  "homepage": "https://github.com/HiroAgustin/astro-buffer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HiroAgustin/astro-buffer.git"
+  },
+  "keywords": [
+    "astro-integration",
+    "withastro",
+    "buffer",
+    "social-media"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "format:check": "prettier --check src test",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "astro": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "astro": "^7.4.5",
+    "prettier": "^3.9.10",
+    "typescript": "^6.0.3"
+  }
+}