@k9o/gate-react-native 1.0.0 → 1.1.0

package/README.md

@@ -1,77 +1,216 @@
 # @k9o/gate-react-native
 
-The official React Native SDK for the [Kilimanjaro](https://kilimanjaro.dev) Gate Identity-Aware Kernel.
-
-**Version**: 0.3.0 | **Platform**: RN 0.74+ (New Architecture) | **TypeScript**: 5.3+
-
-## Installation
-
-```sh
+Kilimanjaro Gate for React Native. Sign end users in with email and password and refresh their session.
+The refresh token stays in the device keychain.
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Refresh and sign out](#refresh-and-sign-out)
+- [Token storage](#token-storage)
+- [Custom claims](#custom-claims)
+- [Handle errors](#handle-errors)
+- [Appendix](#appendix)
+  - [Requirements](#requirements)
+  - [Client options](#client-options)
+  - [Methods](#methods)
+  - [Error codes](#error-codes)
+  - [Related packages](#related-packages)
+
+## Install
+
+```bash
 npm install @k9o/gate-react-native react-native-keychain
-# or
-yarn add @k9o/gate-react-native react-native-keychain
 ```
 
-## Quickstart
+Yarn works too: `yarn add @k9o/gate-react-native react-native-keychain`. See [requirements](#requirements) for versions.
+
+## Quick start
+
+The examples use a `tasks` app whose users sign in to the `member-portal` project. See [client options](#client-options) for the constructor.
 
 ```ts
-import { GateClient } from '@k9o/gate-react-native';
+import { GateClient } from "@k9o/gate-react-native";
 
 const gate = new GateClient({
-  orgBaseUrl: 'https://acme.api.k9o.io',
-  projectSlug: 'my-project',
+  orgBaseUrl: "https://acme.api.k9o.io",
+  projectSlug: "member-portal",
 });
+```
 
-// Sign in
-const result = await gate.signIn({ email: 'user@example.com', password: 'password' });
-console.log(result.user.id);          // eu_...
+Sign in. The refresh token is saved to the keychain for you.
+
+```ts
+const result = await gate.signIn({ email: "user@example.com", password: "correct-horse" });
+
+console.log(result.user.email);
 console.log(result.session.expiresAt);
+```
+
+```text
+user@example.com
+2026-01-15T10:30:00.000Z
+```
+
+The result has a `user` and a `session`. See [methods](#methods).
+
+## Refresh and sign out
+
+With no arguments, `refreshToken` reads the stored token and saves the new one.
 
-// Refresh (reads Keychain automatically)
+```ts
 const refreshed = await gate.refreshToken();
 
-// Sign out (clears Keychain automatically)
+console.log(refreshed.session.expiresAt);
+```
+
+```text
+2026-01-15T11:30:00.000Z
+```
+
+`signOut` ends the session on the server and clears the keychain. It does nothing if no token is stored.
+
+```ts
 await gate.signOut();
 ```
 
-## Native Keychain
+## Token storage
+
+By default the refresh token lives in the iOS Keychain or Android Keystore, through `react-native-keychain`.
 
-Refresh tokens are persisted via `react-native-keychain` — iOS Keychain / Android Keystore. Inject a custom `TokenStore` for alternative persistence:
+To store it elsewhere, pass a `TokenStore`. This one keeps it in memory, which suits tests.
 
 ```ts
-import type { TokenStore } from '@k9o/gate-react-native';
+import { GateClient } from "@k9o/gate-react-native";
+import type { TokenStore } from "@k9o/gate-react-native";
+
+class MemoryTokenStore implements TokenStore {
+  private token: string | null = null;
+
+  async save(token: string): Promise<void> {
+    this.token = token;
+  }
+
+  async load(): Promise<string | null> {
+    return this.token;
+  }
+
+  async delete(): Promise<void> {
+    this.token = null;
+  }
+}
 
-class MyStore implements TokenStore { ... }
 const gate = new GateClient({
-  orgBaseUrl: '...',
-  projectSlug: '...',
-  tokenStore: new MyStore(),
+  orgBaseUrl: "https://acme.api.k9o.io",
+  projectSlug: "member-portal",
+  tokenStore: new MemoryTokenStore(),
 });
 ```
 
 ## Custom claims
 
+Claims added by extensions appear on the access token under their namespace. Decoding does not verify the signature.
+
 ```ts
-import { AccessToken } from '@k9o/gate-react-native';
+import { AccessToken } from "@k9o/gate-react-native";
 
 const token = AccessToken.decode(result.session.accessToken);
-const role = token?.customClaims['partners']?.['partner_role'];
+
+if (token !== null) {
+  const claims = token.customClaims;
+  const partners = claims["partners"];
+
+  if (partners !== undefined) {
+    const role = partners["partner_role"];
+    console.log(role);
+  }
+}
+```
+
+```text
+extension_org_admin
 ```
 
-## Error handling
+`token` also has `subject`, `issuer`, `issuedAt`, `expiresAt` and `allClaims`.
+
+## Handle errors
+
+Every failure is a `GateError`. Check `code`.
 
 ```ts
-import { GateError } from '@k9o/gate-react-native';
+import { GateError } from "@k9o/gate-react-native";
 
 try {
-  await gate.signIn({ email, password });
-} catch (e) {
-  if (e instanceof GateError) {
-    switch (e.code) {
-      case 'INVALID_CREDENTIALS': break;
-      case 'NETWORK': break;
-      case 'UNKNOWN': console.log(e.statusCode, e.body); break;
-    }
+  await gate.signIn({ email: "user@example.com", password: "wrong" });
+} catch (error) {
+  if (error instanceof GateError && error.code === "INVALID_CREDENTIALS") {
+    console.log(error.message);
   }
 }
 ```
+
+```text
+Invalid credentials.
+```
+
+See [error codes](#error-codes) for all of them.
+
+## Appendix
+
+### Requirements
+
+| Requirement | Version |
+|---|---|
+| React | 18 or later |
+| React Native | 0.74 or later |
+| `react-native-keychain` | 8 or later (follow its native setup) |
+| TypeScript (optional) | 5.3 or later |
+
+### Client options
+
+`new GateClient({ orgBaseUrl, projectSlug, tokenStore? })`
+
+| Option | Required | Meaning |
+|---|---|---|
+| `orgBaseUrl` | Yes | Your organization's API host, such as `https://acme.api.k9o.io` |
+| `projectSlug` | Yes | The project users sign in to |
+| `tokenStore` | No | Where the refresh token is kept; the keychain by default |
+
+### Methods
+
+| Method | What it does |
+|---|---|
+| `signIn({ email, password })` | Sign in; resolves to `{ user, session }` |
+| `refreshToken({ refreshToken?, projectHint? })` | Rotate the session; uses the stored token when none is passed |
+| `signOut({ refreshToken? })` | End the session and clear the stored token |
+| `AccessToken.decode(jwt)` | Read an access token's claims; `null` if it is not a JWT |
+
+| Result field | Contents |
+|---|---|
+| `user` | `id`, `email`, `status`, `roles`, `groups`, timestamps |
+| `session` | `accessToken`, `refreshToken`, `expiresAt` |
+
+### Error codes
+
+| Code | When |
+|---|---|
+| `INVALID_CREDENTIALS` | Wrong email or password |
+| `UNAUTHENTICATED` | The session expired, or no refresh token is stored |
+| `FORBIDDEN` | The session is not allowed to do this |
+| `NETWORK` | The request could not reach the server |
+| `DECODING` | The response was not in the expected shape |
+| `UNKNOWN` | Any other response; `statusCode` and `body` are set |
+
+### Related packages
+
+| Package | Purpose |
+|---|---|
+| `@k9o/kibo-react-native` | Client-side encryption with your own KMS |
+| `@k9o/core` | The TypeScript SDK for the rest of the platform |
+
+Documentation: <https://kilimanjaro.dev>
+
+## License
+
+Apache-2.0 © Formelo Inc. See `LICENSE` and `NOTICE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k9o/gate-react-native",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Kilimanjaro Gate IAK SDK for React Native",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/GateAuthClient.ts

@@ -3,7 +3,7 @@ import { parseEnvelope } from "./Models";
 
 /**
  * Internal fetch-based transport layer for @k9o/gate-react-native.
- * Constructs URLs using the v2.5.68 `/@<projectSlug>/gate/<suffix>` grammar.
+ * Constructs URLs using the `/@<projectSlug>/gate/<suffix>` grammar.
  */
 export class GateAuthClient {
   private readonly baseUrl: string;

package/src/GateClient.ts

@@ -63,7 +63,7 @@ export class GateClient {
    * If `refreshToken` is omitted, loads the token from the store.
    * Updates the store with the new refresh token on success.
    *
-   * `projectHint` is optional per ch03 §3.9; omit for most configurations.
+   * `projectHint` is optional; omit for most configurations.
    *
    * Mirrors: `POST /@<projectSlug>/gate/refresh`
    */

package/src/GateError.ts

@@ -67,9 +67,9 @@ export class GateError extends Error {
 
 // MARK: - Wire error parsing
 
-// The gateway emits a KError at the ROOT of the error body per ch01 §10.4:
+// The gateway emits a KError at the ROOT of the error body:
 // `{ code, message, context?, recommendation? }` — NOT wrapped in `{ error: … }`.
-// Codes are platform-namespaced (`K9O_*` per the ch11 error namespace), so the
+// Codes are platform-namespaced (`K9O_*`), so the
 // prefix is stripped before matching the SDK's typed enum.
 interface WireKError {
   code?: string;

package/src/Models.ts

@@ -29,7 +29,7 @@ export interface AuthResult {
   session: Session;
 }
 
-/** Standard ch01 §1 response envelope. */
+/** Standard response envelope. */
 interface Envelope<T> {
   data: T;
   meta?: Record<string, unknown>;
@@ -54,7 +54,7 @@ export function parseEnvelope<T>(body: string): T {
 /**
  * Lightweight access-token decoder. Decodes the JWT payload without
  * signature verification. Exposes `ext.<namespace>.<name>` custom-claim
- * flatten from v2.5.65.
+ * flatten from.
  */
 export class AccessToken {
   readonly subject: string | undefined;
@@ -72,7 +72,7 @@ export class AccessToken {
   }
 
   /**
-   * Custom claims namespaced under `ext.<namespace>` per v2.5.65.
+   * Custom claims namespaced under `ext.<namespace>` per.
    * `customClaims['partners']?.['partner_role']` → "extension_org_admin"
    */
   get customClaims(): Record<string, Record<string, unknown>> {