@kodepik/ums-sdk

UMS (User Management System) SDK for JavaScript/TypeScript — single package with multiple entry points for browser, React, Vue, Express, and NestJS.

Install

npm install @kodepik/ums-sdk
# or
pnpm add @kodepik/ums-sdk

Entry Points

| Import path | Use case | |---|---| | @kodepik/ums-sdk | Core utilities (types, permission helpers, token decode) | | @kodepik/ums-sdk/browser | Browser client (login redirect, storage, auto-refresh) | | @kodepik/ums-sdk/react | React Provider, hooks, guard components | | @kodepik/ums-sdk/vue | Vue plugin, composable, route guard | | @kodepik/ums-sdk/server | Express middleware + JWKS token verification | | @kodepik/ums-sdk/nest | NestJS module, guard, decorators |

Quick Start

React

import { UmsProvider, useUms, PermissionGate } from '@kodepik/ums-sdk/react';

// main.tsx
<UmsProvider config={{ baseUrl: 'https://ums.company.com', appId: 'my-app', callbackUrl: '/auth/callback' }}>
  <App />
</UmsProvider>

// component.tsx
function Dashboard() {
  const { user, login, logout, can } = useUms();

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

  return (
    <div>
      <p>Hello {user.email}</p>
      <PermissionGate module="reports" permission="read">
        <ReportsWidget />
      </PermissionGate>
      <button onClick={() => logout()}>Logout</button>
    </div>
  );
}

// callback page
import { useUmsClient } from '@kodepik/ums-sdk/react';
function AuthCallback() {
  const client = useUmsClient();
  useEffect(() => { client.handleCallback(); navigate('/'); }, []);
  return <p>Loading...</p>;
}

Vue 3

// main.ts
import { UmsPlugin } from '@kodepik/ums-sdk/vue';
app.use(UmsPlugin, { baseUrl: 'https://ums.company.com', appId: 'my-app' });

// component.vue
import { useUms } from '@kodepik/ums-sdk/vue';
const { user, isAuthenticated, login, logout, can } = useUms();
// template: <div v-if="can('reports', 'read')">...</div>

Express

import { umsAuth, requirePermission } from '@kodepik/ums-sdk/server';

app.use('/api', umsAuth({ baseUrl: process.env.UMS_BASE_URL! }));
app.get('/api/reports', requirePermission('reports', 'read'), (req, res) => {
  res.json({ user: req.umsUser });
});

NestJS

import { UmsModule, UmsGuard, RequirePermission, UmsUser as UmsUserDec } from '@kodepik/ums-sdk/nest';

@Module({
  imports: [UmsModule.register({ baseUrl: process.env.UMS_BASE_URL!, global: true })],
})
export class AppModule {}

@Controller('reports')
export class ReportsController {
  @Get()
  @RequirePermission('reports', 'read')
  getReports(@UmsUserDec() user: UmsUser) {
    return { user };
  }
}

Browser (Vanilla / Any Framework)

import { UmsClient } from '@kodepik/ums-sdk/browser';

const ums = new UmsClient({
  baseUrl: 'https://ums.company.com',
  appId: 'my-app',
  callbackUrl: 'https://myapp.com/callback',
});

// Login
ums.login();

// On callback page
ums.handleCallback();

// Authenticated fetch with auto-refresh
const res = await ums.fetch('/api/data');

// Check permissions
if (ums.can('reports', 'read')) { /* show reports */ }

Core Utilities

Available from any entry point:

import { decodeToken, isTokenExpired, hasPermission, hasRole, hasModule } from '@kodepik/ums-sdk';

const user = decodeToken(token);
if (user && hasPermission(user, 'dashboard', 'write')) {
  // authorized
}

Token Lifecycle

1. ums.login() → redirects to UMS → Keycloak → callback with ?token=...&refresh_token=...
2. ums.handleCallback() → stores tokens
3. ums.getToken() → returns valid token (auto-refreshes if expired)
4. ums.fetch(url) → attaches Bearer header, retries on 401
5. ums.logout() → clears local + redirects to UMS centralized logout

Custom Token Storage

import { UmsClient } from '@kodepik/ums-sdk/browser';
import type { TokenStorage } from '@kodepik/ums-sdk';

const cookieStorage: TokenStorage = {
  getToken: () => getCookie('ums_token'),
  getRefreshToken: () => getCookie('ums_refresh'),
  setTokens: (t, rt) => { setCookie('ums_token', t); setCookie('ums_refresh', rt); },
  clear: () => { deleteCookie('ums_token'); deleteCookie('ums_refresh'); },
};

const ums = new UmsClient({ baseUrl: '...', appId: '...', storage: cookieStorage });