@samkiel/authsdk

Official authentication SDK for SAMKIEL products. Provides a unified, multi-environment auth client for Browsers, Node.js, Next.js, and CLI tools.

Features

• 🌐 Multi-Environment: Auto-detects and adapts to Browser, Node.js, and CLI contexts.
• 🍪 Cookie-First: Seamlessly handles httpOnly cookies for secure browser authentication.
• ⚛️ React Ready: Includes high-level hooks (useAuth, useUser) and an AuthProvider.
• ⚡ Next.js Optimized: Edge-ready middleware and Server Component helpers.
• 💻 CLI Tool: Built-in CLI for managing sessions in terminal environments.

Installation

npm install @samkiel/authsdk

Usage

Core Client (Universal)

import { SamkielAuth } from '@samkiel/authsdk';

const auth = new SamkielAuth({
  baseUrl: 'https://id.samkiel.tech',
});

// Login
await auth.login('[email protected]', 'password');

// Get User
const user = await auth.getUser();
console.log(user.email);

// Logout
await auth.logout();

Functional Client (createClient)

For consumers who prefer a flat function API, use createClient. The baseUrl option is optional and defaults to https://id.samkiel.tech — override it to point at a staging or self-hosted SAMKIEL ID deployment.

import { createClient } from '@samkiel/authsdk';

// Defaults to https://id.samkiel.tech
const auth = createClient();

// Or override for staging / self-hosted
const stagingAuth = createClient({ baseUrl: 'https://id.staging.samkiel.tech' });

await auth.login('[email protected]', 'password');
const user = await auth.getUser();
await auth.logout();

Usernames & SAMKIEL ID

Every user has a permanent SAMKIEL ID (samkielId, e.g. SKL-A4X9K2) and a unique username. Sign-in accepts any of email, username, or SAMKIEL ID via a single identifier:

// Object form (preferred)
await auth.signIn({ identifier: 'ezekiel', password: 'password' });        // username
await auth.signIn({ identifier: 'SKL-A4X9K2', password: 'password' });     // SAMKIEL ID
await auth.signIn({ identifier: '[email protected]', password: 'password' });  // email

// Legacy positional form still works — `email` is treated as the identifier
await auth.login('[email protected]', 'password');

// Registration takes an optional username (required by the backend)
await auth.register('Ezekiel Brown', '[email protected]', 'password', 'ezekiel_dev');

// Live registration helpers
const { available } = await auth.checkUsernameAvailability('ezekiel_dev');
const { suggestion } = await auth.suggestUsername('Ezekiel Brown');

// Change the username (once every 23 days)
import { UsernameChangeCooldownError } from '@samkiel/authsdk';
try {
  const updated = await auth.changeUsername('new_handle');
} catch (err) {
  if (err instanceof UsernameChangeCooldownError) {
    console.log(`Next change allowed at ${err.nextChangeAt}`);
  }
}

React Integration

Wrap your app in the AuthProvider:

import { AuthProvider } from '@samkiel/authsdk/react';

function App() {
  return (
    <AuthProvider baseUrl="https://id.samkiel.tech">
      <Main />
    </AuthProvider>
  );
}

Use hooks in your components:

import { useAuth, useUser } from '@samkiel/authsdk/react';

function Profile() {
  const { user, isLoading } = useUser();
  const { logout } = useAuth();

  if (isLoading) return <p>Loading...</p>;
  if (!user) return <button onClick={() => login(...)}>Login</button>;

  return (
    <div>
      <p>Welcome, {user.email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Next.js Integration

Route Protection (Middleware)

// middleware.ts
import { samkielMiddleware } from '@samkiel/authsdk/next';

export default samkielMiddleware({
  baseUrl: 'https://id.samkiel.tech',
  protectedRoutes: ['/dashboard', '/settings'],
  loginPage: '/login', // optional
});

Server Sessions (Server Components)

import { getServerSession } from '@samkiel/authsdk/next';

export default async function Dashboard() {
  const user = await getServerSession('https://id.samkiel.tech');
  
  if (!user) return <p>Access Denied</p>;
  
  return <div>Welcome back, {user.email}</div>;
}

CLI Tool

The SDK includes a global CLI for authentication:

# Login
samkiel-authsdk login [email protected] password

# Check status
samkiel-authsdk whoami
samkiel-authsdk status

# Logout
samkiel-authsdk logout

Admin Client (Lighthouse & Admin Tools)

The AdminClient provides access to protected administrative endpoints. It requires a token from a user with the admin role.

import { AdminClient } from '@samkiel/authsdk';

const admin = new AdminClient(
  'https://id.samkiel.tech', 
  'your-admin-session-token'
);

// Get Dashboard Stats
const stats = await admin.getDashboardStats();
console.log(`Total Users: ${stats.totalUsers}`);

// Manage Users
const { users } = await admin.getUsers({ search: 'ezekiel', limit: 10 });
await admin.suspendUser('user-id', true);

// Look up a user by email, username, or SAMKIEL ID
const user = await admin.getUserByIdentifier('SKL-A4X9K2');

// Fetch Studio Metrics
const kivMetrics = await admin.getKivMetrics();

Development

Scripts

• npm run build: Build the package (ESM/CJS/Types).
• npm run dev: Build and watch for changes.
• npm run lint: Run type checking.

Structure

• src/core: Framework-agnostic logic.
• src/react: React context and hooks.
• src/next: Next.js middleware and server-side helpers.
• src/cli: CLI implementation and file-based token storage.

License

ISC © SAMKIEL