@chesterbrains/translify-cli 0.8.0 → 0.8.2

package/README.md

@@ -309,9 +309,101 @@ When the project has **Require review** turned on in Translify:
 - `publish` refuses when a translation that would go live has a placeholder error (a missing or extra placeholder, invalid ICU, a printf type mismatch). Nothing is published, the refused translations are listed like `lint` lists them, and the command exits 6. Warnings never block. On an environment with **Publish approved text only**, only approved translations count: one carried over from its last approved text never blocks. `--allow-errors` publishes anyway and reports how many went out with errors; the publish is recorded in the activity log with the override.
 - `pull --only-approved` writes the approved text from the working copy and leaves out translations that were never approved, for building a release bundle without publishing. `status --only-approved` compares against the same. It works with `--from working` only: environments already apply the gate.
 
+## Webhooks
+
+A project's admins can add webhooks under **Integrations**. Translify calls them with `publication.created` every time
+an environment's live batch changes: a publish, a rollback or an unpublish (`batch.kind` says which). A publish whose
+result is identical to what is live emits nothing. `ping` is the test event, sent by "Send test" and by the
+verification dispatch that saves a GitHub webhook.
+
+Deliveries are made by a worker, not by the request that published: five attempts, waiting 1 minute, 5 minutes,
+30 minutes and 2 hours between them, then the delivery is `DEAD` and can be resent from the app. The log keeps 30
+days. The delivery id is the same on every attempt (`X-Translify-Delivery` and the payload's `id`), so a receiver that
+answers slowly and gets the retry can dedupe on it. Answer 2xx as soon as the request is accepted and do the work
+afterwards; the sender waits 10 seconds.
+
+### Payload
+
+```json
+{
+  "id": "<delivery id>",
+  "event": "publication.created",
+  "createdAt": "2026-10-25T14:02:11.000Z",
+  "project": { "id": "…", "slug": "shop", "name": "Shop" },
+  "environment": { "id": "…", "slug": "production", "name": "Production", "requireApproved": true },
+  "batch": {
+    "id": "…", "seq": 41, "kind": "PUBLISH",
+    "publishedCount": 1280, "addedCount": 3, "changedCount": 14, "removedCount": 0,
+    "withheldCount": 0, "errorCount": 0
+  },
+  "actor": { "type": "user", "id": "…", "name": "Anna Rossi" }
+}
+```
+
+`addedCount`, `changedCount` and `removedCount` are the batch's diff against the previous live batch: a first publish
+has everything in `addedCount`; an `UNPUBLISH` has `publishedCount: 0` and everything that went offline in
+`removedCount`. "Did anything change" is the sum of the three. `withheldCount` is what a `requireApproved` gate kept
+back, `errorCount` the cells that went live with placeholder errors (a publish with `--allow-errors` or the app's
+"publish anyway", or a rollback, which skips the gate). `actor.type` is `user`, `apiKey`
+(a CLI publish; `name` is the key's name) or `system`. A `ping` carries `id`, `event`, `createdAt`, `project` and
+`webhook { id, target, destination }` only.
+
+### Verify a delivery
+
+Generic webhooks `POST` the payload as `application/json` to an `https://` URL on a public host, with:
+
+| Header | Value |
+| --- | --- |
+| `X-Translify-Event` | `publication.created` or `ping` |
+| `X-Translify-Delivery` | the delivery id, identical on every attempt |
+| `X-Translify-Timestamp` | unix seconds when the attempt was sent |
+| `X-Translify-Signature` | `v1=<hex hmac-sha256(secret, "<timestamp>.<body>")>` |
+| `User-Agent` | `translify-webhooks/1` |
+
+The signing secret is shown once when the webhook is created: a generated `whsec_…`, or the 16 to 255 characters you
+supplied. Verify over the raw body, compare in constant time and refuse a timestamp more than 300 s (5 minutes) away
+from now:
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function verify(rawBody, headers, secret) {
+  const timestamp = Number(headers['x-translify-timestamp']);
+  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
+  const expected = `v1=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`;
+  const given = Buffer.from(String(headers['x-translify-signature'] ?? ''));
+  const wanted = Buffer.from(expected);
+  return given.length === wanted.length && timingSafeEqual(given, wanted);
+}
+```
+
+### GitHub
+
+A webhook with the **GitHub** target sends a
+[`repository_dispatch`](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event) instead:
+`POST https://api.github.com/repos/<owner>/<repo>/dispatches` with `event_type` `translify.publication` (or
+`translify.ping`) and the payload above as `client_payload`. No signature: GitHub authenticates the token.
+
+The token is a fine-grained personal access token with **Contents: Read and write** on that one repository (that is
+the permission `repository_dispatch` needs). Translify verifies it with a `translify.ping` dispatch before saving and
+refuses a token or repository GitHub rejects; the expiry GitHub reports is shown in the list from 14 days out.
+
+[`recipes/github-actions/translify-pull-on-publish.yml`](https://github.com/chesterbrains/translify-cli/blob/main/recipes/github-actions/translify-pull-on-publish.yml)
+is the workflow that closes the loop: on `translify.publication` it runs `translify pull --from env:<slug>` for the
+environment in the payload, commits, opens a pull request whose body carries the publish summary (batch, counts,
+actor), runs the build step you add and merges. Three things to set after copying it: the repository setting **Allow
+GitHub Actions to create and approve pull requests** (Settings → Actions → General; without it the job token cannot
+open the PR); the environment the repository follows, a literal in the job's `if:`, with the webhook limited to that
+environment in Translify since every environment pulls into the same files; and your build in the commented Build
+step, so a pull that does not compile leaves the pull request open instead of merging. The workflow builds and merges
+inside the same run because a pull request opened with `GITHUB_TOKEN` never triggers other workflows; a protected
+default branch needs the Merge step removed or a bypass for the token. The
+[translify-examples](https://github.com/chesterbrains/translify-examples/blob/main/.github/workflows/translify-pull-on-publish.yml)
+repository runs this workflow against the demo project.
+
 ## CI (GitHub Actions)
 
-Store the key in the repository secrets as `TRANSLIFY_SECRET_KEY`. Two ready-made workflows live in
+Store the key in the repository secrets as `TRANSLIFY_SECRET_KEY`. Three ready-made workflows live in
 [`recipes/github-actions/`](https://github.com/chesterbrains/translify-cli/tree/main/recipes/github-actions); copy the
 one you need to `.github/workflows/` as it is.
 
@@ -323,8 +415,11 @@ one you need to `.github/workflows/` as it is.
 - [`translify-release.yml`](https://github.com/chesterbrains/translify-cli/blob/main/recipes/github-actions/translify-release.yml)
   is for apps that bundle translations at build time: `lint`, then `pull`, your build, then `publish` to the environment
   chosen in the Actions tab (or on a tag). Key scopes: `PULL` and `PUBLISH`.
+- [`translify-pull-on-publish.yml`](https://github.com/chesterbrains/translify-cli/blob/main/recipes/github-actions/translify-pull-on-publish.yml)
+  runs when Translify's GitHub webhook announces a publish: `pull --from env:<slug>` for the published environment,
+  commit, a pull request with the publish summary, your build, merge. Key scope: `PULL`. Setup in [Webhooks](#webhooks).
 
-Both use `npx -y translify`, so they follow every 0.x release; pin a version (`npx -y @chesterbrains/translify-cli@0.6`) if a breaking
+All three use `npx -y translify`, so they follow every 0.x release; pin a version (`npx -y @chesterbrains/translify-cli@0.6`) if a breaking
 release must not turn the workflow red on its own.
 
 Fail a pull request when local files drift from Translify:

package/dist/version.js

@@ -1,3 +1,3 @@
 // Must equal package.json "version"; src/version.test.ts fails when they drift.
-export const VERSION = '0.8.0';
+export const VERSION = '0.8.2';
 export const USER_AGENT = `translify-cli/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chesterbrains/translify-cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Push, pull and publish Translify translations from your repository",
   "license": "MIT",
   "repository": {