@witnium-tech/witniumchain 0.3.0 → 0.6.0

package/README.md.bak

@@ -1,160 +0,0 @@
-# @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.