npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@syndew/oluso-sdk

v1.30.1

Published

Oluso JavaScript SDK for embedding journeys and forms

Readme

@syndew/oluso-sdk

JavaScript/TypeScript SDK for Oluso. Includes journey forms (waitlists, surveys), authentication (inline/modal journeys and OIDC redirect), role/permission checks, and drop-in embed scripts.

Installation

npm install @syndew/oluso-sdk

Packages

| Entry Point | Description | |-------------|-------------| | @syndew/oluso-sdk | Core client + auth SDK (ESM/CJS) | | @syndew/oluso-sdk/react | React components and hooks | | @syndew/oluso-sdk/embed | Drop-in <script> for journey modals | | @syndew/oluso-sdk/auth | Auth SDK standalone (ESM/CJS) | | @syndew/oluso-sdk/auth-embed | Drop-in <script> for auth modals |


Journey Forms

Vanilla JavaScript

import { createClient } from '@syndew/oluso-sdk';

const oluso = createClient({
  serverUrl: 'https://auth.yoursite.com',
  tenant: 'acme',
  apiKey: 'pk_...', // Optional
});

// Get journey info (form fields)
const journey = await oluso.getJourney('waitlist');
console.log(journey.fields); // [{ name: 'email', type: 'email', ... }]

// Submit data
const result = await oluso.submit('waitlist', {
  email: '[email protected]',
  name: 'John Doe',
});

if (result.success) {
  console.log('Submitted!', result.submissionId);
}

React

import { OlusoProvider, JourneyForm, useJourney } from '@syndew/oluso-sdk/react';

function App() {
  return (
    <OlusoProvider config={{ serverUrl: 'https://auth.yoursite.com', tenant: 'acme' }}>
      <WaitlistPage />
    </OlusoProvider>
  );
}

// Pre-built form component
function WaitlistPage() {
  return (
    <JourneyForm
      slug="waitlist"
      onSuccess={() => console.log('Thanks!')}
      submitText="Join Waitlist"
    />
  );
}

// Headless hook for custom UI
function CustomForm() {
  const { journey, values, setValue, submit, isSubmitting, fieldErrors } = useJourney({
    slug: 'waitlist',
    onSuccess: (result) => console.log('Submitted!', result),
  });

  if (!journey) return <div>Loading...</div>;

  return (
    <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
      {journey.fields.map((field) => (
        <div key={field.name}>
          <label>{field.label}</label>
          <input
            type={field.type}
            value={values[field.name] as string || ''}
            onChange={(e) => setValue(field.name, e.target.value)}
            required={field.required}
          />
          {fieldErrors[field.name] && <span>{fieldErrors[field.name]}</span>}
        </div>
      ))}
      <button type="submit" disabled={isSubmitting}>Submit</button>
    </form>
  );
}

Multi-Step Journeys

Any journey can run step by step from your own UI. Each call returns the session: the step to render (session.step, with its type and model) or the completion.

const oluso = createClient({ serverUrl: 'https://auth.yoursite.com', tenant: 'acme' });

let session = await oluso.startJourney('onboarding-survey');
while (session.status === 'in_progress') {
  const input = await renderStep(session.step);          // your UI for session.step
  session = await oluso.submitStep(session.sessionId, input);
}

if (session.completed) {
  console.log(session.message);
}

oluso.getSession(sessionId) returns where a session stands without running it. Authentication journeys run inline through the auth client (auth.signIn(data)), which completes them with tokens.

Drop-in Embed (No Build Step)

Add the script to any HTML page. Buttons with data-oluso-trigger open a modal form:

<script src="https://cdn.oluso.io/sdk/embed.js"></script>

<button data-oluso-trigger="waitlist">Join Waitlist</button>
<button data-oluso-trigger="demo">Request Demo</button>

<script>
  Oluso.init({
    serverUrl: 'https://auth.yoursite.com',
    tenant: 'acme',
    journeys: {
      waitlist: { title: 'Join the Waitlist' },
      demo: { title: 'Request a Demo' },
    },
  });
</script>

Programmatic API:

Oluso.open('waitlist');
Oluso.close();

Embedding a journey in your own iframe

Journeys can ask for documents and photos (a file field with Take a photo, the Business Verification step's supporting documents, or a verification provider's widget that captures ID or a selfie). Browsers only give an iframe the camera and microphone when the host page allows it, so include allow="camera; microphone":

<iframe
  src="https://auth.yoursite.com/journey/start/merchant-signup"
  allow="camera; microphone"
  style="border:none;width:100%;min-height:640px"
  title="Merchant sign-up"></iframe>

JourneyEmbed (React) and the modal sign-in (auth.signIn()) set this for you. If your site sends a Permissions-Policy header, it must also allow camera and microphone for the auth server's origin (e.g. Permissions-Policy: camera=(self "https://auth.yoursite.com")).


Authentication

The auth SDK provides inline and modal authentication (using the journey system) and standard OIDC redirect flow, plus role and permission checking.

Setup

import { OlusoAuth } from '@syndew/oluso-sdk';

const auth = new OlusoAuth({
  serverUrl: 'https://auth.yoursite.com',
  tenant: 'acme',
  clientId: 'my-spa-client',
  storage: 'localStorage', // 'memory' | 'localStorage' | 'sessionStorage'
  onAuthStateChange: (user) => {
    console.log('Auth state:', user);
  },
});

Modal Sign-In (Secure Iframe)

Call signIn() without arguments to open a secure modal. Credentials are entered inside an iframe hosted on the auth server — the host page never has access to passwords:

// Opens modal, resolves when auth completes
const result = await auth.signIn();

if (result.success) {
  console.log('Logged in:', result.user.name);
}

This is the recommended approach for most integrations. It works on any site (first-party or third-party) and handles MFA, password reset, etc. inside the iframe automatically.

Programmatic Sign-In (First-Party Only)

For trusted first-party apps where you control the page and collect credentials yourself. The journey runs step by step through the headless journey API and completes with an authorization code bound to this client's PKCE verifier, which the SDK redeems for tokens:

const result = await auth.signIn({
  username: '[email protected]',
  password: 'secret',
});

if (result.success) {
  console.log('Logged in:', result.user.name);
  console.log('Token:', result.tokens.accessToken);
} else if (result.requiresStep) {
  // MFA or another step: result.step describes what to render
  const mfaResult = await auth.continueStep(result.sessionId, {
    code: '123456',
  });
} else {
  console.error(result.error); // e.g. invalid credentials
}

The calling page's origin must be registered for the client (one of its CORS origins, or the origin of one of its redirect URIs); a journey's own allowed origins can narrow that further. The client must be enabled and allow the authorization code grant, the scopes must be ones the client is allowed, and a PKCE S256 challenge is required (the SDK sends one). The same rules apply to every sign-in that returns a code to the page: the modal, passkeys and FedCM.

Security note: Programmatic sign-in passes credentials through JavaScript on the host page. Only use this on pages you fully control. For third-party sites or untrusted environments, use the modal approach above.

Sign-Up

// Modal (secure)
const result = await auth.signUp();

// Or programmatic (first-party)
const result = await auth.signUp({
  name: 'Jane Doe',
  email: '[email protected]',
  password: 'securePassword123',
});

OIDC Redirect Flow

For apps that prefer the standard redirect-based flow:

// Redirect to login page
await auth.loginWithRedirect({
  prompt: 'login', // Optional: 'login' | 'consent' | 'none'
  state: '/dashboard', // Optional: return path
});

// On callback page (/callback)
const result = await auth.handleCallback();
if (result.success) {
  window.location.href = '/dashboard';
}

Checking Roles & Permissions

const user = auth.getUser();

// Single role check
if (auth.hasRole('admin')) {
  showAdminPanel();
}

// Any of multiple roles
if (auth.hasAnyRole('admin', 'editor', 'moderator')) {
  showEditButton();
}

// Permission check
if (auth.hasPermission('documents:write')) {
  enableUpload();
}

// Access user claims directly
console.log(user.email);
console.log(user.tenantId);
console.log(user.claims); // Raw ID token claims

Token Management

// Get access token for API calls
const token = auth.getAccessToken();
fetch('/api/data', {
  headers: { Authorization: `Bearer ${token}` },
});

// Refresh token
const refreshed = await auth.refreshToken();

// Check auth state
if (auth.isAuthenticated()) { ... }

// Fetch updated user info from server
const user = await auth.fetchUserInfo();

Logout

// Local logout (clear tokens)
auth.logout();

// Logout with server-side session end
auth.logout({ redirect: true });

// Custom post-logout redirect
auth.logout({
  redirect: true,
  postLogoutRedirectUri: 'https://yoursite.com/goodbye',
});

Passkeys (WebAuthn)

Sign in with passkeys — no form, no iframe, just a native biometric/key prompt. Works with discoverable credentials (usernameless) and username-based flows.

// Discoverable credential (shows all passkeys for this site)
const result = await auth.signInWithPasskey();

// Username-based (shows passkeys for a specific user)
const result = await auth.signInWithPasskey({ username: '[email protected]' });

// Conditional mediation (passkey suggestions in autofill)
const ac = new AbortController();
const result = await auth.signInWithPasskey({ conditional: true, signal: ac.signal });

if (result.success) {
  console.log('Signed in with passkey:', result.user.name);
}

Note: Passkeys require the FIDO2 plugin to be enabled on the server (and passkeys not turned off for the tenant). Users must have previously registered a passkey via their account settings. The page's origin must be registered for the client and the scopes allowed for it, as for programmatic sign-in above.

FedCM (Browser-Native Account Picker)

FedCM enables browser-native federated sign-in without redirects or popups. The browser shows an account picker if the user has an active session on the auth server.

const result = await auth.signInWithFedCM();

// With login hint to pre-select an account
const result = await auth.signInWithFedCM({ loginHint: '[email protected]' });

// Silent re-authentication (if user previously approved)
const result = await auth.signInWithFedCM({ autoReauth: true });

if (result.success) {
  console.log('Signed in via FedCM:', result.user.name);
}

Browser support: Chrome 132+, Edge 132+ (the SDK binds the code to the page with a PKCE challenge sent in the provider's params). Returns an error on unsupported browsers — use as a progressive enhancement alongside modal sign-in. The page's origin must be registered for the client.

OIDC Endpoint Discovery

Endpoints are automatically discovered from .well-known/openid-configuration. You can also specify them manually:

const auth = new OlusoAuth({
  serverUrl: 'https://auth.yoursite.com',
  tenant: 'acme',
  clientId: 'my-spa-client',
  endpoints: {
    authorization: 'https://auth.yoursite.com/connect/authorize',
    token: 'https://auth.yoursite.com/connect/token',
    userinfo: 'https://auth.yoursite.com/connect/userinfo',
    endSession: 'https://auth.yoursite.com/connect/endsession',
  },
});

Drop-in Auth Embed (No Build Step)

Add auth to any site with a single script tag:

<script src="https://cdn.oluso.io/sdk/auth-embed.js"></script>

<button data-oluso-auth="signin">Sign In</button>
<button data-oluso-auth="signup">Create Account</button>
<button data-oluso-auth="passkey">Sign In with Passkey</button>

<script>
  OlusoAuth.init({
    serverUrl: 'https://auth.yoursite.com',
    tenant: 'acme',
    clientId: 'my-spa-client',
    storage: 'localStorage',
  });

  // Listen for auth state changes
  OlusoAuth.onAuth((user) => {
    if (user) {
      document.getElementById('greeting').textContent = `Hello, ${user.name}`;
    }
  });
</script>

Programmatic API:

OlusoAuth.open('signin');  // Open sign-in modal
OlusoAuth.open('signup');  // Open sign-up modal
OlusoAuth.close();

// Passkey & FedCM (no modal needed)
OlusoAuth.signInWithPasskey();           // Native passkey prompt
OlusoAuth.signInWithFedCM();             // Browser account picker

// After auth
OlusoAuth.getUser();              // { sub, name, email, roles, permissions, ... }
OlusoAuth.hasRole('admin');       // true/false
OlusoAuth.hasPermission('read'); // true/false
OlusoAuth.logout();

Configuration Reference

OlusoConfig (Journey Client)

| Option | Type | Required | Description | |--------|------|----------|-------------| | serverUrl | string | Yes | Base URL of your Oluso server | | tenant | string | Yes | Your tenant ID or subdomain | | apiKey | string | No | Public API key | | fetch | typeof fetch | No | Custom fetch implementation (SSR) |

OlusoAuthConfig (Auth Client)

| Option | Type | Required | Description | |--------|------|----------|-------------| | serverUrl | string | Yes | Base URL of your Oluso server | | tenant | string | Yes | Your tenant ID or subdomain | | clientId | string | Yes | OAuth2 client ID (public client) | | redirectUri | string | No | Redirect URI for OIDC code flow | | scopes | string | No | Scopes to request (default: openid profile email) | | endpoints | OidcEndpoints | No | Manual OIDC endpoint overrides | | signInJourney | string | No | Slug of the sign-in journey (default: signin) | | signUpJourney | string | No | Slug of the sign-up journey (default: signup) | | passwordResetJourney | string | No | Slug of the password-reset journey | | storage | string | No | Token storage: memory, localStorage, sessionStorage | | apiKey | string | No | Public API key, sent as X-API-Key | | onAuthStateChange | function | No | Callback when auth state changes |


Events

const oluso = createClient({ ... });

oluso.on('submission:success', (event) => {
  console.log('Submitted:', event.data);
});

Event types: journey:started, journey:step, journey:completed, journey:error, submission:success, submission:error, auth:success, auth:error. Each event carries the journey's slug; journey events also carry the sessionId.


TypeScript

All types are exported:

import type {
  OlusoConfig,
  JourneyInfo,
  JourneyField,
  SubmissionResult,
  OlusoAuthConfig,
  OlusoUser,
  TokenSet,
  AuthResult,
  OidcEndpoints,
  JourneySession,
  JourneyStepView,
  StepResult,
  JourneyStepData,
} from '@syndew/oluso-sdk';