@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-sdkPackages
| 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 claimsToken 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';