@witnium-tech/witniumchain

TypeScript SDK for the WitniumChain accounts service — identity, billing, organisation administration, OAuth sessions, and delegated-signing-key management.

Status

v0.1 — low-level "shell" client. One method per OpenAPI route, five auth modes selectable on a single client. Thread 4 of Phase C will layer three higher-level clients on top:

WitniumchainClient (end-user) — wraps signup, login, subscriptions, delegated-key one-call provisioning, account management.
WitniumchainOrgClient (org admin) — wraps user provisioning, Stripe Connect onboarding.
WitniumchainAdminClient (sysadmin) — wraps org lifecycle, key rotation, credit adjustment.

For now, this shell client is what's published. Every type comes from the OpenAPI spec via openapi-typescript; a CI drift test in the parent repo gates regeneration on every change.

Install

npm install @witnium-tech/witniumchain

Auth model

The accounts service accepts five distinct credentials. Configure whichever you need on the client; methods that require a credential you didn't supply throw at call time.

Credential	Header / Cookie	Used by
`sessionCookie`	`Cookie: wac_session=…`	`/v1/auth/logout`, `/v1/account/`, `/v1/billing/`, `/v1/keys/`, `/v1/contracts/{pause,unpause}`, `/v1/oauth/sessions`
`accessToken`	`Authorization: Bearer <JWT>`	`/v1/users/me/delegated-keys/*`, `/v1/sign`
`orgApiKey`	`Authorization: Bearer wcorg_live_…`	`/v1/orgs/me/*`
`adminToken`	`Authorization: Bearer <ADMIN_TOKEN>`	`/v1/admin/*`
`signedRequest`	`X-Witnium-Key/Timestamp/Signature`	`/v1/contracts/{addr}/witnesses/{propose,sign,finalize,revoke}`

Public routes need no credential (/v1/auth/{signup,verify,login,…}, /v1/contracts/provision, GET /v1/contracts/{addr}/witnesses/{id}, /health/*).

Examples

import { WitniumchainClient } from '@witnium-tech/witniumchain';

const client = new WitniumchainClient({
  baseUrl: 'https://auth.witniumchain.com',
});

await client.signup({ email: 'alice@example.com', password: 'correct horse battery staple' });
// User clicks email link, lands on /verify?token=…
const { provisioningToken } = await client.verifyEmail('the-token-from-the-link');

// Then login (sets the wac_session cookie in a browser; in Node, capture
// from response headers and pass back via `sessionCookie`).
await client.login({ email: 'alice@example.com', password: '…' });

Org admin — create a user

const org = new WitniumchainClient({
  baseUrl: 'https://auth.witniumchain.com',
  orgApiKey: 'wcorg_live_…',
});

const { userId, provisioningToken } = await org.createOrgUser({
  email: 'bob@customer.example.com',
});
// Forward `provisioningToken` to Bob — he calls /v1/contracts/provision
// with locally-generated owner + signing keypairs.

Sysadmin — create an organisation

const sys = new WitniumchainClient({
  baseUrl: 'https://auth.witniumchain.com',
  adminToken: process.env.ACCOUNTS_ADMIN_TOKEN!,
});

const { organization, apiKey } = await sys.createOrganization({
  name: 'Acme Inc.',
  email: 'ops@acme.example.com',
  accountType: 'metered',
  signupGrantAmount: 100,
});
// `apiKey` is shown ONCE — store it now.

OAuth API — delegated-key + sign

const api = new WitniumchainClient({
  baseUrl: 'https://auth.witniumchain.com',
  accessToken: bearerJwt,
});

const prepared = await api.prepareDelegatedKey({ contractAddress: '0x…' });
// Sign prepared.messageToSign with your owner key locally:
const ownerSignature = await myOwnerSigner.sign(prepared.messageToSign);

const submitted = await api.submitDelegatedKey(prepared.id, { ownerSignature });
// submitted.confirmed === true once the addSigningKey tx mines (~10–15 s).

const { signature } = await api.sign(
  { delegatedKeyId: prepared.id, payload: 'deadbeef…' },
);

SDK signed-request (witness propose/sign/finalize)

const sdk = new WitniumchainClient({
  baseUrl: 'https://auth.witniumchain.com',
  signedRequest: {
    publicKeyHex: 'abcd…64-chars…',
    sign: async (canonicalMessage) => {
      // Sign with your Ed25519 key — e.g. via @noble/ed25519 or a KMS.
      // Return the 128-char hex signature.
      return await myEd25519Sign(canonicalMessage);
    },
  },
});

const intent = await sdk.proposeWitness('0x…', {
  dataId: '…64-hex…',
  requiredSigners: ['…signer-pubkey…'],
});

Errors

All non-2xx responses surface as WitniumchainApiError:

import { WitniumchainApiError } from '@witnium-tech/witniumchain';

try {
  await client.createOrgUser({ email: 'taken@example.com' });
} catch (err) {
  if (err instanceof WitniumchainApiError) {
    console.error(err.status, err.errorLabel, err.message);
    // err.body holds the raw parsed body for advanced inspection.
  }
}

License

MIT.