# Publishing `@hadawi/sdk`

## Prerequisites (one-time)

1. Create an npm automation token with publish rights for the `@hadawi` org/user.
2. In the GitHub repo settings → **Secrets and variables → Actions**, add:
   - `NPM_TOKEN` — the npm automation token
3. (Recommended) On npm, enable [provenance](https://docs.npmjs.com/generating-provenance-statements) for the package so CI publishes are attested.

> **API docs hosting:** GitHub Pages is not available for this private org repo on the current plan.
> TypeDoc HTML is copied into `packages/web/public/sdk-api/` and shown at **`/docs/sdk/api`**.

## Release flow

1. Bump the version and changelog in `packages/sdk`:

   ```bash
   # from packages/sdk
   # edit package.json version + CHANGELOG.md Unreleased → X.Y.Z
   ```

2. Commit on `main`:

   ```bash
   git add packages/sdk/package.json packages/sdk/CHANGELOG.md
   git commit -m "chore(sdk): release vX.Y.Z"
   git push origin main
   ```

3. Tag and push (this triggers `.github/workflows/publish-sdk.yml`):

   ```bash
   git tag sdk-vX.Y.Z
   git push origin sdk-vX.Y.Z
   ```

   The tag **must** match `package.json` version (`sdk-v0.1.0` ↔ `"version": "0.1.0"`).

4. Optional dry-run without publishing:
   - GitHub → Actions → **Publish @hadawi/sdk** → Run workflow → check **dry_run**

## What the publish workflow does

- Installs workspace deps with pnpm
- Verifies `sdk-v*` tag matches `package.json`
- Lints + builds (`tsup` CJS/ESM/IIFE + `.d.ts`)
- Packs a tarball as a smoke check
- Publishes with `--access public --provenance`

## API docs (TypeDoc → `/sdk-api` on the web app)

CI verifies TypeDoc still builds (Actions → **Build @hadawi/sdk API docs**).

To ship an updated API reference with the web deploy:

```bash
cd packages/sdk
pnpm run docs:web
# writes packages/web/public/sdk-api/
git add ../web/public/sdk-api
git commit -m "docs(sdk): refresh TypeDoc API reference"
```

Local preview:

```bash
pnpm run docs          # packages/sdk/docs/ (gitignored)
# or after docs:web:
open ../web/public/sdk-api/index.html
# live (prod): https://beta.hadawi.sa/docs/sdk/api
# staging:     https://dev.hadawi.sa/docs/sdk/api
```

Merchant quick-start (in-app): `/docs/sdk`  
Full TypeDoc API reference: `/docs/sdk/api`

## Manual publish (escape hatch)

```bash
cd packages/sdk
pnpm run lint
pnpm run build
pnpm publish --access public --no-git-checks
```

Prefer the tag-based CI flow so provenance and version checks stay intact.