NONS React Authentication SDK

@nons/sdk-react

Official React/Frontend Authentication SDK for the NONS Platform, built to interface seamlessly with Ory Kratos, Ory Hydra, and the API Gateway bridge.

📋 Table of Contents

1. Installation Guide
2. SDK Usage Guide
3. Development Guide
4. Release Guide
5. Consumer Setup

🚀 Installation Guide

Install the package directly from GitHub Packages:

Using NPM

npm install @nons/sdk-react

Using PNPM

pnpm add @nons/sdk-react

To configure GitHub Packages registry, add the following to your .npmrc file:

@nons:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

📖 SDK Usage Guide

1. Initialize the Client

Instantiate NonsClient with your API Gateway bridge endpoint and a StorageAdapter:

import { NonsClient, StorageAdapter } from "@nons/sdk-react";

class LocalStorageStorageAdapter implements StorageAdapter {
  getAccessToken() { return localStorage.getItem("access_token"); }
  setAccessToken(token: string) { localStorage.setItem("access_token", token); }
  getRefreshToken() { return localStorage.getItem("refresh_token"); }
  setRefreshToken(token: string) { localStorage.setItem("refresh_token", token); }
  clearTokens() {
    localStorage.removeItem("access_token");
    localStorage.removeItem("refresh_token");
  }
}

export const nonsClient = new NonsClient({
  baseUrl: "https://api.nons.ir",
  storage: new LocalStorageStorageAdapter(),
  timeout: 10000,
});

2. Magic Code Flow

Step A: Initialize Flow & Request Code

const flow = await nonsClient.auth.initializeLoginFlow();
const flowId = flow.id; // Save this to submit with verification code

await nonsClient.auth.sendMagicCode(flowId, "[email protected]");

Step B: Submit Verification Code (OTP)

const session = await nonsClient.auth.verifyMagicCode(flowId, "123456");
const onboardingRequired = nonsClient.auth.isOnboardingRequired(session);

if (onboardingRequired) {
  // Redirect to Onboarding profile form
} else {
  // Login successful
}

3. Google OIDC Login

Construct the browser redirection URL and navigate the user to complete Google Consent verification:

const loginChallenge = "hydra_login_challenge_from_query_params";
const googleLoginUrl = nonsClient.auth.getGoogleLoginUrl(loginChallenge);

// Redirect the browser
window.location.assign(googleLoginUrl);

4. Session & Logout

Check the active session or logout:

// Get Kratos Session
const session = await nonsClient.auth.getCurrentSession();

// Logout
const logoutChallenge = "hydra_logout_challenge";
await nonsClient.auth.logout(logoutChallenge);

🛠️ Development Guide

Install Dependencies

pnpm install

Run Tests

The test suite utilizes Vitest to validate all authentication methods, error parsing, and timeout behaviors:

pnpm test

Build the Package

Compiles TypeScript files and exports types to the dist directory:

pnpm run build

📦 Release Guide

The package is versioned and published independently:

1. Increment Version: Update version in package.json according to semver.
2. Commit and Tag: Commit the changes and create a git tag matching the version:

   git add package.json
   git commit -m "chore: release v1.0.0"
   git tag v1.0.0

3. Publish to GitHub Packages: Pushing the tag triggers the GitHub Actions release workflow automatically. Alternatively, run:

   pnpm run build
   pnpm publish

🌐 Consumer Setup

Instructions for setting up consumer projects (like auth-ui):

1. Local Development

To develop and test changes locally without publishing to GitHub Packages:

• Option A (File reference): Use a relative path dependency in package.json:

  "@nons/sdk-react": "file:../sdk-react"

• Option B (Symlinking): Link the package using pnpm link:

  cd sdk-react && pnpm link --global
  cd ../auth-ui && pnpm link --global @nons/sdk-react

2. CI Pipelines

For GitHub Actions or other CI runners to resolve the dependency, configure a GITHUB_TOKEN environment variable with package read permission:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '22'
    registry-url: 'https://npm.pkg.github.com'
    scope: '@nons'
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. Vercel Deployment

To deploy consumer applications to Vercel:

1. Ensure the .npmrc file is present in the repository root:

   @nons:registry=https://npm.pkg.github.com/
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Navigate to your Vercel Project Settings -> Environment Variables.
3. Create a new variable named GITHUB_TOKEN and paste your GitHub Personal Access Token (PAT) with read:packages scope as the value.
4. Trigger the deployment. Vercel will resolve, download, and build the project successfully.