> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nometria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Upstream Sync

> Contract-aware SDK fork maintenance — auto-applies safe upstream changes, flags breaking ones.

`sdk-upstream-sync` solves fork drift. If you maintain a fork of any npm or GitHub SDK, upstream ships changes, your fork drifts, and you find out when something breaks in production. This tool diffs API contracts, auto-applies safe changes, and generates an investigation report for anything risky.

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/nometria/sdk-upstream-sync">
    nometria/sdk-upstream-sync
  </Card>

  <Card title="npm" icon="npm" href="https://www.npmjs.com/package/@nometria-ai/sdk-upstream-sync">
    @nometria-ai/sdk-upstream-sync
  </Card>
</CardGroup>

## Install

```bash theme={null}
npm install --save-dev @nometria-ai/sdk-upstream-sync
```

## Setup

```bash theme={null}
# Required
export UPSTREAM_REPO=original-org/javascript-sdk
export GITHUB_TOKEN=ghp_...           # avoids rate limits

# Optional
export UPSTREAM_BRANCH=main           # default: main
export MAX_FILES=20                   # auto-apply threshold
export MAX_LOC=600                    # auto-apply threshold
```

## Usage

```bash theme={null}
# Run sync from your fork directory
npx sdk-upstream-sync

# Add to package.json scripts
{
  "scripts": {
    "sync": "UPSTREAM_REPO=original-org/sdk npx sdk-upstream-sync"
  }
}
```

## How it works

| Step                     | What happens                                                                |
| ------------------------ | --------------------------------------------------------------------------- |
| **1. Fetch**             | Gets the latest upstream commit SHA — exits cleanly if already in sync      |
| **2. Extract contracts** | Reads exports, methods, and module structure from both sides via GitHub API |
| **3. Diff contracts**    | Detects removed exports/methods as breaking, new ones as safe additions     |
| **4. Check thresholds**  | Auto-applies if: ≤ 20 files changed, ≤ 600 LOC, zero breaking changes       |
| **5. Apply or report**   | Patches your fork, or generates `sync/report.md` for manual review          |

## Safety thresholds

| Condition                                  | Action                             |
| ------------------------------------------ | ---------------------------------- |
| ≤ 20 files, ≤ 600 LOC, no breaking changes | Auto-apply patch                   |
| > 20 files changed                         | Generate investigation report only |
| > 600 LOC changed                          | Generate investigation report only |
| Any breaking change detected               | Generate investigation report only |

## Automate with GitHub Actions

```yaml theme={null}
# .github/workflows/sdk-sync.yml
name: Upstream SDK sync
on:
  schedule:
    - cron: '0 9 * * 1'   # Every Monday at 9am
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install --save-dev @nometria-ai/sdk-upstream-sync
      - run: npx sdk-upstream-sync
        env:
          UPSTREAM_REPO: original-org/javascript-sdk
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

<Note>This tool was originally built to maintain Nometria's fork of the Base44 JavaScript SDK and keep it in sync with upstream API changes automatically.</Note>