@zimoos/sdk

Public ZimoOS SDK for applications that use ZimoOS for application login, private runtime config, application-user data, checkout, checkout status, and entitlement reads.

Install

npm install @zimoos/sdk

The package is public and contains SDK call wrappers only. Published runtime files are minified JavaScript without source maps or TypeScript source files. Type declarations are included for integration safety. Do not put service credentials, private runtime values, payment provider internals, or application secrets into the package. The SDK must never expose payment-provider API keys, webhook signing keys, provider webhook IDs, raw provider payloads, or payment-provider catalog IDs; those remain ZimoOS Admin/server-side concerns.

Browser

import {
  buildApplicationLoginUrl,
  parseApplicationLoginCallback,
} from '@zimoos/sdk/browser';

The browser entry exports URL builders and callback parsing helpers only. It does not expose a browser client factory, does not accept service credentials, and must not call internal APIs.

ZimoOS always owns login, registration, password recovery, third-party login, account confirmation, account switching, and consent. A business application must not add its own credential form. An existing ZimoOS browser session still lands on “continue / switch account / cancel”; it is never silently authorized.

Web callbacks must be an exact complete HTTPS URI registered by Admin. Wildcard, origin-only, and near-match callbacks are rejected. They remain confidential_web and exchange through the business backend. New web callbacks require PKCE S256 by default; existing callbacks remain compatible until Admin enables pkceRequired. Keep the verifier in an HttpOnly server-side session and pass it only when exchanging the one-time code:

Admin still classifies the callback: caller-supplied PKCE does not upgrade a confidential_web registration into a native_public client.

const session = await zimoos.exchangeApplicationLoginCode({ code, codeVerifier });
if (!session.user.emailVerified) {
  // Campaign enrollment must fail closed and ask for email verification.
}

emailVerified is canonical ZimoOS identity state. Applications must not infer it from the email string, provider, or an earlier session.

Native

import { createZimoosNativeClient } from '@zimoos/sdk/native';

const zimoos = createZimoosNativeClient({
  baseUrl: 'https://api-staging.zimoos.com',
  applicationSlug: 'mteam',
  redirectUri: 'mteam://auth/zimoos',
  expectedEnvironment: 'staging',
  secureStorage,
  requestTimeoutMs: 15_000,
});

const attempt = await zimoos.startLogin();
await shell.openExternal(attempt.authorizationUrl);

// Call only after Electron/macOS/Windows delivers the exact deep link.
const session = await zimoos.handleDeepLink(callbackUrl);

The native entry owns PKCE S256, state, nonce, the ten-minute request expiry, exact deep-link parsing, one-time code exchange, session verification, token rotation, revocation, and secure persistence through the injected NativeSecureStorage adapter. Admin must register the exact custom URI with clientType=native_public. Native clients never receive or store a Client Secret. Every SDK network operation has a bounded timeout (15 seconds by default, configurable from 1–60 seconds). Electron code should contain only shell.openExternal, protocol-event delivery, and a safeStorage adapter.

Checkout URLs are not browser-built. A business backend calls createBillingCheckout() with priceSlug, idempotencyKey, and its application session, then returns the one-time ZimoOS-owned checkoutUrl to the browser. The browser must not construct a checkout URL from checkoutSessionId.

Node

import { createZimoosNodeClient } from '@zimoos/sdk/node';

const zimoos = createZimoosNodeClient({
  baseUrl: process.env.ZIMOOS_BASE_URL!,
  clientId: process.env.ZIMOOS_CLIENT_ID!,
  clientSecret: process.env.ZIMOOS_CLIENT_SECRET!,
});

The Node entry is server-only. Keep clientId, clientSecret, application session tokens, and private runtime config values out of browser code.

Publish

Publishing is intentionally GitHub-only. First review the package locally:

npm run sdk:pack

sdk:pack builds the control plane, prepares packages/sdk/dist, and performs an npm dry run so the package contents can be reviewed before publishing.

After an explicit release decision, run one command from the repository root:

npm run release:package -- --package sdk --version <exact-version>

The command triggers the protected workflow from staging, waits for the exact request, and verifies the immutable version and integrity on public npm. The workflow re-runs every release gate and publishes one verified tarball with a short-lived npm OIDC identity. Local npm run sdk:publish is blocked; no npm password, one-time code, or long-lived write token belongs in the repository or GitHub secrets. Add --plan to inspect the release without dispatching it.

The npm package's one-time Trusted Publisher must name organization zimoos, repository zimoos, workflow publish-package.yml, environment npm-publish, and allow only npm publish.

An owner can establish that trust from the CLI once:

npm run release:package:bootstrap -- --package sdk --version <exact-version> --confirm-cli-only-release-policy

npm may require human 2FA for this one settings change. Routine releases use only the release command above and never require npm login.