chore(sdk): add build, publish metadata, and release process for @acc…

.changeset/add-sdk-build-and-release.md

@@ -0,0 +1,5 @@
+---
+'@accensa/sdk': minor
+---
+
+Initial published release of `@accensa/sdk` with build pipeline, package metadata, and release process.

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": ["@changesets/changelog-github", { "repo": "accensa/accensa-app" }],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/ci.yml

@@ -131,3 +131,63 @@ jobs:
       - name: Build Next.js app
         working-directory: ./apps/web
         run: pnpm build
+
+  verify-pack:
+    name: verify SDK tarball
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install pnpm
+        run: npm install -g pnpm@9
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build SDK
+        working-directory: ./packages/sdk
+        run: pnpm build
+      - name: Pack SDK tarball
+        working-directory: ./packages/sdk
+        run: pnpm pack --pack-destination /tmp/sdk-tarball
+      - name: Verify tarball installs and imports in ESM and CJS
+        run: |
+          TARBALL=$(ls /tmp/sdk-tarball/*.tgz)
+
+          # Create scratch project outside the workspace
+          SCRATCH=$(mktemp -d)
+          cd "$SCRATCH"
+          npm init -y > /dev/null 2>&1
+          npm install "$TARBALL" > /dev/null 2>&1
+
+          # Test CJS import
+          node -e "
+            const sdk = require('@accensa/sdk');
+            if (typeof sdk.verifyReceipt !== 'function') throw new Error('verifyReceipt not exported');
+            if (typeof sdk.attachAccensaHook !== 'function') throw new Error('attachAccensaHook not exported');
+            if (typeof sdk.createSettleHook !== 'function') throw new Error('createSettleHook not exported');
+            console.log('CJS: root entry OK');
+          "
+
+          # Test CJS merkle import
+          node -e "
+            const merkle = require('@accensa/sdk/merkle');
+            if (typeof merkle.verifyReceipt !== 'function') throw new Error('verifyReceipt not exported from /merkle');
+            console.log('CJS: merkle entry OK');
+          "
+
+          # Test ESM import
+          cat > "$SCRATCH/test.mjs" << 'EOF'
+          import { verifyReceipt, attachAccensaHook, createSettleHook } from '@accensa/sdk';
+          import { verifyReceipt as vr } from '@accensa/sdk/merkle';
+
+          if (typeof verifyReceipt !== 'function') throw new Error('verifyReceipt not exported');
+          if (typeof attachAccensaHook !== 'function') throw new Error('attachAccensaHook not exported');
+          if (typeof createSettleHook !== 'function') throw new Error('createSettleHook not exported');
+          if (typeof vr !== 'function') throw new Error('verifyReceipt not exported from /merkle');
+          console.log('ESM: both entries OK');
+          EOF
+          node "$SCRATCH/test.mjs"
+
+          echo "All import checks passed"

.github/workflows/publish.yml

@@ -0,0 +1,122 @@
+name: Publish @accensa/sdk
+
+on:
+  push:
+    tags:
+      - '@accensa/sdk@*'
+
+jobs:
+  build-and-test:
+    name: build & test SDK
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install pnpm
+        run: npm install -g pnpm@9
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build SDK
+        working-directory: ./packages/sdk
+        run: pnpm build
+      - name: Test SDK
+        working-directory: ./packages/sdk
+        run: pnpm test
+      - name: Typecheck SDK
+        working-directory: ./packages/sdk
+        run: pnpm typecheck
+      - name: Verify conformance vectors are reproducible
+        run: |
+          node packages/sdk/scripts/generate-vectors.mjs
+          git diff --exit-code -- packages/sdk/merkle-vectors.json packages/sdk/vectors.rs
+
+  verify-pack:
+    name: verify tarball
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install pnpm
+        run: npm install -g pnpm@9
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build SDK
+        working-directory: ./packages/sdk
+        run: pnpm build
+      - name: Pack SDK tarball
+        working-directory: ./packages/sdk
+        run: pnpm pack --pack-destination /tmp/sdk-tarball
+      - name: Verify tarball installs and imports in ESM and CJS
+        run: |
+          TARBALL=$(ls /tmp/sdk-tarball/*.tgz)
+
+          # Create scratch project outside the workspace
+          SCRATCH=$(mktemp -d)
+          cd "$SCRATCH"
+          npm init -y > /dev/null 2>&1
+          npm install "$TARBALL" > /dev/null 2>&1
+
+          # Test CJS import
+          node -e "
+            const sdk = require('@accensa/sdk');
+            if (typeof sdk.verifyReceipt !== 'function') throw new Error('verifyReceipt not exported');
+            if (typeof sdk.attachAccensaHook !== 'function') throw new Error('attachAccensaHook not exported');
+            if (typeof sdk.createSettleHook !== 'function') throw new Error('createSettleHook not exported');
+            console.log('CJS: root entry OK');
+          "
+
+          # Test CJS merkle import
+          node -e "
+            const merkle = require('@accensa/sdk/merkle');
+            if (typeof merkle.verifyReceipt !== 'function') throw new Error('verifyReceipt not exported from /merkle');
+            console.log('CJS: merkle entry OK');
+          "
+
+          # Test ESM import
+          cat > "$SCRATCH/test.mjs" << 'EOF'
+          import { verifyReceipt, attachAccensaHook, createSettleHook } from '@accensa/sdk';
+          import { verifyReceipt as vr } from '@accensa/sdk/merkle';
+
+          if (typeof verifyReceipt !== 'function') throw new Error('verifyReceipt not exported');
+          if (typeof attachAccensaHook !== 'function') throw new Error('attachAccensaHook not exported');
+          if (typeof createSettleHook !== 'function') throw new Error('createSettleHook not exported');
+          if (typeof vr !== 'function') throw new Error('verifyReceipt not exported from /merkle');
+          console.log('ESM: both entries OK');
+          EOF
+          node "$SCRATCH/test.mjs"
+
+          echo "All import checks passed"
+
+  publish:
+    name: publish to npm
+    needs: verify-pack
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install pnpm
+        run: npm install -g pnpm@9
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build SDK
+        working-directory: ./packages/sdk
+        run: pnpm build
+      - name: Publish with provenance
+        working-directory: ./packages/sdk
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CONTRIBUTING.md

@@ -6,7 +6,7 @@ We welcome contributions from the community! Whether it's a bug fix, new feature
 
 1. **Fork the repository** on GitHub.
 2. **Clone your fork** locally.
-3. **Find an issue**: Look for issues labeled with `good first issue` if you are a new contributor. If you have an idea for a feature or found a bug, please create a new issue first to discuss it with the maintainers before starting work.
+3. **Find an issue**: Look for issues labeled with `good first issue` if you are a new contributor. If you have an idea for a feature or found a bug, please create an issue first to discuss it with the maintainers before starting work.
 4. **Wait for assignment**: To avoid duplicate work, please express your interest on the issue and wait for a maintainer to assign it to you before starting work.
 5. **Create a new branch** for your feature or bug fix (`git checkout -b feature/my-new-feature` or `bugfix/issue-123`).
 6. **Make your changes** and test them thoroughly.
@@ -36,4 +36,81 @@ CI will reject unformatted code via `pnpm format:check`.
 If you find a bug or have a feature idea, please open an issue on GitHub using our issue templates.
 Include as much detail as possible to help us understand and resolve the issue quickly.
 
-Thank you for helping make Accensa better!
+---
+
+## `@accensa/sdk` Release Process
+
+### Semver Policy
+
+The SDK follows [Semantic Versioning](https://semver.org/). The following are
+considered **breaking changes** (major bumps):
+
+- Changes to `SettleHookPayload` fields (the JSON body POSTed to
+  `/api/hook/settle`).
+- Changes to the Ed25519 signing mechanism or signature encoding.
+- Removal or renaming of any exported symbol.
+- Changes to the `X-Signature` header contract.
+
+The report payload and signature scheme are a **wire contract** between the SDK
+and the Accensa indexer. A change that the indexer does not also accept is a
+breaking change even if the TypeScript types are compatible.
+
+Non-breaking additions (new optional fields, new exports, bug fixes) are minor
+or patch bumps as usual.
+
+### Changesets
+
+This monorepo uses [Changesets](https://github.com/changesets/changesets) to
+manage versioning and changelogs.
+
+When you land a change that affects `@accensa/sdk`:
+
+```bash
+pnpm changeset
+```
+
+Follow the prompts to select the package and bump type, then write a summary
+that will appear in the changelog. Commit the generated
+`.changeset/*.md` file with your PR.
+
+### Cutting a Release
+
+1. **Merge the release PR.** Changesets opens a "Version Packages" PR
+   automatically when changesets accumulate on `main`. Merge it to bump
+   `package.json` versions and update `CHANGELOG.md`.
+
+2. **Tag the release.** After the version PR merges, tag the commit:
+
+   ```bash
+   git tag @accensa/sdk@<version>
+   git push origin @accensa/sdk@<version>
+   ```
+
+3. **CI publishes on tag.** The `publish` workflow in
+   `.github/workflows/publish.yml` detects the tag, builds the package, runs
+   the tarball verification job, and publishes to npm with provenance.
+
+### Manual Release (if needed)
+
+If you need to publish manually outside the automated flow:
+
+```bash
+cd packages/sdk
+pnpm build
+pnpm pack          # inspect the tarball
+npm publish --provenance --access public
+```
+
+### Verifying the Package
+
+Before publishing, verify the packed tarball works in an isolated project:
+
+```bash
+cd packages/sdk
+pnpm build
+pnpm pack
+```
+
+Then create a scratch directory outside the workspace, install the tarball, and
+confirm both entry points resolve in ESM and CJS. This is also run
+automatically in CI (see `.github/workflows/ci.yml`, the `verify-pack` job).

package.json

@@ -5,9 +5,12 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "pnpm --filter web lint && pnpm --filter @accensa/sdk lint",
-    "typecheck": "pnpm --filter web typecheck && pnpm --filter @accensa/sdk typecheck"
+    "typecheck": "pnpm --filter web typecheck && pnpm --filter @accensa/sdk typecheck",
+    "changeset": "changeset"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
     "prettier": "^3.5.3"
   }
 }

packages/sdk/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @accensa/sdk
+
+## 0.1.0
+
+### Initial published release
+
+First publishable release of `@accensa/sdk`. This is the same API that has been
+consumed internally via `workspace:^`; no breaking changes from the workspace
+version.
+
+#### Added
+
+- **Build pipeline:** tsup emits ESM (`.mjs`), CJS (`.js`), and `.d.ts` to
+  `dist/`. Consumers need no TypeScript config.
+- **Package metadata:** `exports` map, `files` whitelist, `sideEffects: false`,
+  repository and bugs URLs.
+- **Package README:** documents `verifyReceipt`, `attachAccensaHook`,
+  `createSettleHook`, the signing contract, and supported runtimes.
+
+#### Note
+
+The report payload (`SettleHookPayload`) and Ed25519 signature scheme are a
+**wire contract** with sellers. Any change to the payload fields or signing
+mechanism is a breaking change and will be released as a major version bump.