SDK Versioning & Upgrades

​

Published packages, today

npm view @openchildsafety/ocss version   # → 0.1.3
npm view @phosra/gatekeeper version      # → 0.2.2
npm view @phosra/mcp version             # → 0.4.0
npm view @phosra/sdk versions            # → [ '0.1.0' ]

​

The semver commitment

# Reproducible — pin exact, no surprise breaks
npm install @phosra/sdk@0.1.0 @openchildsafety/ocss@0.1.3 @phosra/gatekeeper@0.2.2

​

How an SDK version maps to the API version

BASE=https://phosra-api-sandbox-production.up.railway.app
curl -s -o /dev/null -w "v1 → %{http_code}\n" "$BASE/api/v1/platforms"   # → v1 → 200
curl -s -o /dev/null -w "v2 → %{http_code}\n" "$BASE/api/v2/platforms"   # → v2 → 404 (no v2 yet)

​

Deprecation & end-of-life

• A deprecated export keeps working. It gains a @deprecated JSDoc tag naming the replacement; tsc and your editor flag it, but the runtime behavior is unchanged.
• Removal follows semver. At 0.x, a deprecated export can be removed in the next minor (0.2 → 0.3). Once a package reaches 1.0, a deprecated export survives until the next major and its removal is called out in the changelog.
• The wire windows still protect you. The ≥ 90-day deprecation window and ≥ 12-month major-version overlap in the Deprecation policy govern the API surface the SDK calls — so even if you pin an old SDK, the endpoints it depends on do not vanish under it without notice.

​

Native iOS & Android SDK lifecycle

​

Version scheme & how you pin

// URL is the private repo Phosra provides; the version is a semver Git tag.
.package(url: "<private PhosraSDK repo URL>", exact: "1.0.0"),
// …then add "PhosraSDK" to your target's dependencies.

​

Upgrade delivery — no npm outdated

• You are notified by email (the private-preview list) when a new tag/coordinate is cut, with its release note. There is no public dist-tag to poll.
• iOS: bump the exact: version in Package.swift (or the pinned tag in Xcode) and re-resolve the package graph.
• Android: bump the com.phosra:sdk:x.y.z coordinate and re-sync Gradle.
• Re-test on-device, not just build — an enforcement behavior change (like the gatekeeper’s staleness floor) compiles clean but changes runtime verdicts.

​

Deprecation, EOL & support matrix

​

Per-package changelogs

​

Worked example — @phosra/gatekeeper 0.1.x → 0.2.x

• gk.endpointState() → "active" | "revoked" | "stale" | "absent", so you can tell a disconnect ("revoked" → release-to-native, stop polling) from an outage ("stale" → keep enforcing last-known-good, fail-closed).
• an onRevoked({ childRef, endpointLabel }) config callback, fired once on the transition to revoked.

​

Migrating your code

import { createGatekeeper } from "@phosra/gatekeeper";
import type { GatekeeperConfig } from "@phosra/gatekeeper";
import type { SenderKey } from "@openchildsafety/ocss";

// Your platform's Ed25519 signing key, minted at endpoint-bind time. Never inline it —
// load from a secret store. See /sdks/link for how to obtain one.
declare const platformSigningKey: SenderKey;

// 0.1.0 config: note there is NO profileMaxAgeMs and NO onRevoked in this version.
const config: GatekeeperConfig = {
  platformDid:          "did:ocss:your-platform",
  platformKeyId:        "did:ocss:your-platform#key-2026",
  gatekeeperSigningKey: platformSigningKey,
  censusBaseUrl:        "https://phosra-api-sandbox-production.up.railway.app",
  trustRootXB64Url:     process.env.PHOSRA_TRUST_ROOT_X!,   // public root pubkey X
  endpointId:           "endpoint-mia-01",                  // the §9.3(b) bound label
  ratingMappings:       [{ ocssCategory: "content_rating", myField: "maturity", vocabulary: "mpaa" }],
};

const gk = createGatekeeper(config);

// isAllowed is synchronous and returns a Verdict; branch on verdict.decision.
function guard(maturity: string): boolean {
  const verdict = gk.isAllowed({ category: "content_rating", signal: { maturity } });
  return verdict.decision !== "block";
  // 0.1.0 has no endpointState()/onRevoked, so a census outage and a real
  // disconnect are indistinguishable here — the gap 0.2.x closes.
}

npm install @phosra/gatekeeper@0.2.2

​

Worked example — @phosra/mcp 0.2.0 → 0.4.0

{
  "mcpServers": {
    "phosra": {
      "command": "npx",
      "args": ["-y", "@phosra/mcp@0.2.0", "--api-key", "phomcp_…"]
    }
  }
}

npx -y @phosra/mcp@0.4.0 --api-key "$PHOSRA_MCP_TOKEN" <<'EOF' | \
  python3 -c "import sys,json; print(len(json.loads(sys.stdin.readlines()[-1])['result']['tools']), 'tools')"
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"verify","version":"1"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF
# → 79 tools

​

Worked example — @openchildsafety/ocss 0.1.0 → 0.1.3

# Additive within 0.1.x — existing imports keep resolving
npm install @openchildsafety/ocss@0.1.3

import { verifyTrustList } from "@openchildsafety/ocss/trustlist/verify";
import { sealEnvelope }    from "@openchildsafety/ocss/envelope";
// These imports resolve identically on 0.1.0 and 0.1.3 — the barrel is frozen
// against the production-deployed OCSS verbs; new verbs arrive as new subpaths.

​

@phosra/sdk — one line so far

npm install @phosra/sdk@0.1.0   # the only published version today

​

Upgrade checklist

1. Read the changelog entry for the target version — /changelog is the dated record; the package’s own README on npm (npm view <pkg> readme, or the package page’s Readme tab) documents its behavior contract.
2. Check the bump class. Patch (0.2.1 → 0.2.2) is safe; a 0.x minor (0.1 → 0.2) may break — treat it like a major.
3. Pin exact, install, and let tsc surface any @deprecated flags or removed exports.
4. Re-run against the sandbox (https://phosra-api-sandbox-production.up.railway.app) before touching production — the Quickstart path proves your setup end-to-end with no API key.
5. Verify runtime behavior, not just that it compiles — the gatekeeper example above is a compile-clean bump that changes what isAllowed returns.

​

Next steps