@witnium-tech/witniumchain 0.2.0

package/README.md

@@ -0,0 +1,160 @@
+# @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:
+
+- `WitniumAccountsClient` (end-user) — wraps signup, login, subscriptions,
+  delegated-key one-call provisioning, account management.
+- `WitniumAccountsOrgClient` (org admin) — wraps user provisioning, Stripe
+  Connect onboarding.
+- `WitniumAccountsAdminClient` (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
+
+```bash
+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
+
+### End-user signup + login
+
+```ts
+import { WitniumAccountsClient } from '@witnium-tech/witniumchain';
+
+const client = new WitniumAccountsClient({
+  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
+
+```ts
+const org = new WitniumAccountsClient({
+  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
+
+```ts
+const sys = new WitniumAccountsClient({
+  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
+
+```ts
+const api = new WitniumAccountsClient({
+  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)
+
+```ts
+const sdk = new WitniumAccountsClient({
+  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 `WitniumAccountsApiError`:
+
+```ts
+import { WitniumAccountsApiError } from '@witnium-tech/witniumchain';
+
+try {
+  await client.createOrgUser({ email: 'taken@example.com' });
+} catch (err) {
+  if (err instanceof WitniumAccountsApiError) {
+    console.error(err.status, err.errorLabel, err.message);
+    // err.body holds the raw parsed body for advanced inspection.
+  }
+}
+```
+
+## License
+
+MIT.