astro-buffalo 0.0.0-stage → 0.2.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,232 @@
-# Temporary Holding Version
+# astro-buffalo
 
-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.
+Share newly published Astro articles to Buffer using its experimental `createContentItem` API.
+One request per article, with a variant for each channel. No SDK, database, or browser JavaScript.
+
+An independent integration; not affiliated with or endorsed by Buffer.
+
+## Setup
+
+Requires Astro 7.x and Node 24 or newer.
+
+```sh
+npm install astro-buffalo
+```
+
+Configure your article endpoint and source directory in `astro.config.mjs`:
+
+```js
+import { defineConfig } from "astro/config";
+import buffer from "astro-buffalo";
+
+export default defineConfig({
+  site: "https://example.com",
+  integrations: [
+    buffer({
+      posts: new URL("./src/buffer-posts.ts", import.meta.url),
+      contentDirectory: "src/content/blog",
+    }),
+  ],
+});
+```
+
+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) => {
+      if (!post.filePath) throw new Error(`Missing source path for "${post.id}".`);
+      return {
+        filePath: post.filePath,
+        title: post.data.title,
+        url: new URL(`/${post.id}/`, site).href,
+      };
+    }),
+  );
+};
+```
+
+The endpoint is injected only during publishing builds and removed before any API requests.
+
+### Article manifest
+
+The endpoint must return a JSON array with these fields on each article:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `filePath` | Yes | Source file path relative to the Astro project root, using forward slashes; no absolute paths or `.`/`..` segments. Must match the Git path, e.g. `src/content/blog/hello.md`. |
+| `title` | Yes | Non-empty article title, also used as the default announcement. |
+| `url` | Yes | Absolute HTTP(S) canonical production URL, without whitespace, credentials, or a fragment. Must match the deployed URL without a redirect. |
+| `text` | No | Non-empty custom announcement text; the article URL is always appended. |
+| `mode` | No | `shareNow` or `addToQueue`; overrides the integration's default for this article. |
+
+An empty array is valid; invalid entries stop the build before any Buffer requests.
+Adapt the collection name and routes to your site. Include only public articles, filtering drafts
+and future dates if your schema defines them:
+
+```ts
+const posts = await getCollection(
+  "blog",
+  ({ data }) => !data.draft && data.pubDate <= new Date(),
+);
+```
+
+### Article detection
+
+The integration compares `BUFFER_BASE_REF` with `HEAD`, sharing added articles and committed
+drafts becoming public. Ordinary edits, published-article renames, and archive entries are ignored.
+Paths are relative to the Astro project root.
+
+For Markdown or MDX drafts, use a top-level YAML boolean `draft: true`. Keep drafts out of your
+public routes and manifest. To publish, set it to `false` or remove it and include the article in
+the manifest. Renaming a draft during publication is supported; sources still marked as drafts
+are never shared.
+
+Quoted strings, custom fields, and schema defaults are not draft flags. Your adapter handles
+custom publication rules and future dates; a date passing without a source change does not trigger
+an announcement. Blog drafts are not synchronized with Buffer.
+
+### Optional settings
+
+By default, announcements publish immediately to every connected, unlocked channel.
+To select channels or use their Buffer posting schedules, add:
+
+```js
+channelIds: ["your_linkedin_channel_id", "your_bluesky_channel_id"],
+mode: "addToQueue",
+```
+
+`channelIds` must be non-empty and contain known IDs. Omit it to use all connected channels.
+`mode` supports `shareNow` (default) and `addToQueue`; both use automatic delivery.
+Disconnected or locked channels are reported and skipped.
+
+For different choices per article, return `mode` in each manifest entry. Articles without a
+mode use the integration setting.
+
+Announcements use `title + "\n\n" + url`. Add `text: post.data.description` to an article's manifest
+entry for custom copy; the content item's title stays unchanged. Custom text is trimmed and must
+be non-empty. The URL is always appended for duplicate detection.
+
+## Publishing
+
+Your site can be hosted anywhere. GitHub Actions is optional: run the publishing build locally
+or in any CI environment with Node 24+ and Git. It needs a Git checkout containing both the
+publishing commit (`HEAD`) and `BUFFER_BASE_REF`; source archives without Git history are not enough.
+If your host cannot provide these, run publishing separately from deployment.
+
+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 articles were added or changed from draft to published. |
+
+Create a personal API key in Buffer's **Settings → API** with `account:read`, `posts:read`,
+and `posts:write` permissions.
+
+Store the key in CI secrets or an ignored `.env` file. The integration reads `process.env`; it
+does not load `.env` itself. Find your organization ID using Buffer's
+`account { organizations { id name } }` query.
+
+### Preview locally
+
+Add your key and organization ID to an ignored `.env` file:
+
+```dotenv
+BUFFER_API_KEY=your_api_key
+BUFFER_ORGANIZATION_ID=your_organization_id
+```
+
+From the commit publishing the articles, run this POSIX shell command (macOS/Linux). Replace `HEAD^`
+with the revision immediately before publication if the changes span multiple commits:
+
+```sh
+BUFFER_PUBLISH=true BUFFER_DRY_RUN=true BUFFER_BASE_REF="$(git rev-parse HEAD^)" \
+  node --env-file=.env ./node_modules/astro/bin/astro.mjs build
+```
+
+Dry runs require credentials and a base revision. They read channels and history, then print the
+planned text, missing channels, and mode. They skip deployment checks and all writes; existing
+failed posts still cause the run to fail.
+
+### GitHub Actions example
+
+After installing the package and committing your lockfile, save this as
+`.github/workflows/buffer.yml`. Configure a `BUFFER_API_KEY` repository secret and a
+`BUFFER_ORGANIZATION_ID` repository variable. Adjust the branch and content path for your site.
+Your normal production deployment must run separately; the integration waits for article URLs
+to become available before creating announcements.
+
+```yaml
+name: Share new articles
+
+on:
+  push:
+    branches: [main]
+    paths: ["src/content/blog/**"]
+  workflow_dispatch:
+    inputs:
+      base_ref:
+        description: Full commit SHA before the new articles (reuse when retrying)
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: buffer-publishing
+  queue: max
+
+jobs:
+  publish:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+      - run: npm ci
+      - run: node ./node_modules/astro/bin/astro.mjs build
+        env:
+          BUFFER_PUBLISH: "true"
+          BUFFER_API_KEY: ${{ secrets.BUFFER_API_KEY }}
+          BUFFER_ORGANIZATION_ID: ${{ vars.BUFFER_ORGANIZATION_ID }}
+          BUFFER_BASE_REF: ${{ github.event.before || inputs.base_ref }}
+```
+
+For a CI preview, add `BUFFER_DRY_RUN: "true"` to the final step's environment. Keep publishing
+out of pull-request and preview deployment workflows. For retries, use manual dispatch with
+the original base SHA; do not replace it with the current commit.
+
+### Deployment and retries
+
+Build from the exact publishing commit with the base revision available in Git. Production URLs
+must respond successfully without redirects; the integration waits up to five minutes for deployment.
+Announcements contain no media, so networks requiring it or extra metadata may reject them.
+
+On failure, rerun with the same base SHA. Every history page is checked for matching URLs per
+channel. Existing failed posts, drafts, or approval requests need attention in Buffer rather than
+replacement posts; keep their records and URL text intact.
+
+Validation finishes before any API requests, but later failures can occur after records are created.
+Inspect Buffer for delivery errors. Creation requests are not retried automatically, and exactly-once
+delivery is not guaranteed. Run publishing builds serially to avoid races.
+
+For development and release instructions, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+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,285 @@
+import { execFileSync } from "node:child_process";
+import { readFile, unlink } from "node:fs/promises";
+import timers from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { z } from "astro/zod";
+import { parse } from "yaml";
+const articlesSchema = z.array(z.object({
+    filePath: z
+        .string()
+        .refine((path) => path.trim() &&
+        !path.startsWith("/") &&
+        !path.includes("\\") &&
+        !path.split("/").some((part) => part === "." || part === "..") &&
+        !/^[a-z]:/i.test(path), "filePath must be a project-relative path using forward slashes."),
+    title: z.string().refine((title) => title.trim(), "title must be a non-empty string."),
+    url: z.string().refine((value) => {
+        if (/\s/.test(value) || !URL.canParse(value))
+            return false;
+        const url = new URL(value);
+        return (["http:", "https:"].includes(url.protocol) && !url.username && !url.password && !url.hash);
+    }, "url must be an absolute HTTP(S) URL without whitespace, credentials, or a fragment."),
+    text: z
+        .string({ message: "announcement text must be a non-empty string." })
+        .refine((text) => text.trim(), "announcement text must be a non-empty string.")
+        .optional(),
+    mode: z.enum(["shareNow", "addToQueue"]).optional(),
+}, { message: "must be an object." }), { message: "Buffer manifest must be an array of articles." });
+function isDraft(source) {
+    const lines = (source.startsWith("\uFEFF") ? source.slice(1) : source).split("\n");
+    if (lines.length < 2 || lines[0].trimEnd() !== "---")
+        return false;
+    const end = lines.findIndex((line, index) => index > 0 && line.trimEnd() === "---");
+    if (end === -1)
+        throw new Error("Missing closing YAML frontmatter delimiter.");
+    const data = parse(lines.slice(1, end).join("\n"));
+    return typeof data === "object" && data !== null && "draft" in data && data.draft === true;
+}
+async function waitForDeployment(url, logger) {
+    const deadline = Date.now() + 300_000;
+    while (Date.now() < deadline) {
+        let response;
+        try {
+            response = await fetch(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 ${url}: ${error.message}. Retrying.`);
+        }
+        if (response) {
+            if (response.ok && response.url === url)
+                return;
+            if (![404, 502, 503, 504].includes(response.status)) {
+                throw new Error(`Cannot verify ${url}: HTTP ${response.status}.`);
+            }
+        }
+        logger.info(`Waiting for ${url} to be deployed...`);
+        await timers.setTimeout(10_000);
+    }
+    throw new Error(`${url} is not live yet. Rerun after deployment succeeds.`);
+}
+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-buffalo",
+        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 contents = await readFile(manifest, "utf8");
+                await unlink(manifest);
+                const result = articlesSchema.safeParse(JSON.parse(contents));
+                if (!result.success) {
+                    throw new Error(result.error.issues
+                        .map(({ path, message }) => [
+                        typeof path[0] === "number" && `Buffer manifest article ${path[0] + 1}`,
+                        path[1] && `(${String(path[1])})`,
+                        message,
+                    ]
+                        .filter(Boolean)
+                        .join(" "))
+                        .join("\n"));
+                }
+                const articles = result.data;
+                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 git = (...args) => execFileSync("git", args, { cwd: fileURLToPath(root), encoding: "utf8" });
+                const changes = git("diff", "--name-status", "--relative", "-z", "--diff-filter=AMR", "--find-renames", base, "HEAD", "--", contentDirectory)
+                    .split("\0")
+                    .filter(Boolean);
+                const previousPaths = new Map();
+                for (let index = 0; index < changes.length;) {
+                    const status = changes[index++];
+                    const path = changes[index++];
+                    if (status.startsWith("R")) {
+                        previousPaths.set(changes[index++], path);
+                    }
+                    else {
+                        previousPaths.set(path, status === "A" ? undefined : path);
+                    }
+                }
+                const posts = articles
+                    .filter(({ filePath }) => {
+                    if (!previousPaths.has(filePath))
+                        return false;
+                    const previousPath = previousPaths.get(filePath);
+                    if (previousPath && !isDraft(git("show", `${base}:./${previousPath}`))) {
+                        return false;
+                    }
+                    return !isDraft(git("show", `HEAD:./${filePath}`));
+                })
+                    .map((article) => ({
+                    ...article,
+                    text: `${article.text?.trim() ?? article.title}\n\n${article.url}`,
+                    mode: article.mode ?? mode,
+                }));
+                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: article.mode,
+                        })}`);
+                        continue;
+                    }
+                    await waitForDeployment(article.url, logger);
+                    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: article.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,48 @@
 {
   "name": "astro-buffalo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Share newly published Astro articles through Buffer.",
+  "license": "MIT",
+  "homepage": "https://github.com/HiroAgustin/astro-buffalo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HiroAgustin/astro-buffalo.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"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "astro": "^7.4.5",
+    "prettier": "^3.9.10",
+    "typescript": "^6.0.3"
+  }
+}