@qelos/integrator-express 4.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+Polyform Shield License 1.0.0
+
+Copyright (c) 2025 Velocitech LTD
+
+Your use of this software is governed by the Polyform Shield License 1.0.0.
+
+You may obtain a copy of the License at:
+https://polyformproject.org/licenses/shield/1.0.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+Additional Terms – Exception Notice:
+
+The author of this software grants additional permissions beyond the Polyform Shield License 1.0.0:
+
+✅ All uses of the software are permitted — including modification, distribution, commercial use, and sublicensing — as long as the software is not used to create, offer, or operate any product or service that competes directly with Qelos (https://qelos.io), a no-code platform for building AI-assisted SaaS applications.
+
+❌ "Direct competition" includes platforms, tools, or services that enable users to visually or programmatically create SaaS applications with the assistance of artificial intelligence.
+
+This exception does not modify the terms of the original Polyform Shield License for other users and applies only by explicit permission of the licensor.

package/README.md

@@ -0,0 +1,163 @@
+# @qelos/integrator-express
+
+Express middleware that calls the Qelos SDK to identify the current user and
+their active workspace before your route handler runs, exposing them on
+`req.qelos.user` / `req.qelos.workspace`.
+
+This is the Express implementation of the Qelos integrator contract — the same
+shape exposed by `@qelos/integrator-nuxt`, `@qelos/plugin-netlify-api`, etc.
+
+## Install
+
+```sh
+npm install @qelos/integrator-express @qelos/sdk
+# express is a peer dependency
+npm install express
+```
+
+## Quick start
+
+```ts
+import express from 'express';
+import { createQelosMiddleware, requireUser } from '@qelos/integrator-express';
+
+const app = express();
+
+app.use(
+  createQelosMiddleware({
+    config: {
+      appUrl: process.env.QELOS_APP_URL!, // e.g. https://yourdomain.com
+    },
+  }),
+);
+
+app.get('/me', (req, res) => {
+  // user/workspace are null when the request is anonymous
+  res.json({
+    user: req.qelos!.user,
+    workspace: req.qelos!.workspace,
+  });
+});
+
+// Short-circuit with 401 when there is no authenticated user:
+app.get(
+  '/private',
+  requireUser((req, res) => {
+    res.json(req.qelos!.user);
+  }),
+);
+```
+
+## What the middleware does
+
+1. Reads the access token from `Authorization: Bearer ...` or the
+   `q_access_token` cookie, and the refresh token from `q_refresh_token`.
+2. Builds a per-request Qelos SDK instance bound to those tokens.
+3. Calls `sdk.authentication.getLoggedInUser()` and
+   `sdk.workspaces.getList()`.
+4. Picks the active workspace (first by default — override with
+   `resolveWorkspace`).
+5. Attaches everything to `req.qelos` and calls `next()`.
+
+The middleware never throws for anonymous requests by default — it just leaves
+`req.qelos.user` and `req.qelos.workspace` as `null`. Pass `requireAuth: true`
+to short-circuit anonymous requests with `401`.
+
+## Token refresh
+
+When the access token is rejected, the SDK tries to recover, in order:
+
+1. The **refresh token** (`q_refresh_token`) via
+   `sdk.authentication.refreshToken()` — issues a new access + refresh pair.
+2. The **cookie token** (the access token cookie itself) via
+   `sdk.authentication.refreshCookieToken()` — used for cookie-only sessions
+   that do not carry a separate refresh token (e.g. social-auth flows).
+
+After a successful refresh the middleware fires the `onTokenRefresh` hook.
+The default implementation writes the new tokens back to the response cookies
+(`HttpOnly`, `SameSite=Lax`, `Secure` whenever `appUrl` is `https://...`).
+
+You can supply your own — for example, to mint your own session cookie or push
+the new tokens into a session store:
+
+```ts
+app.use(
+  createQelosMiddleware({
+    config: { appUrl: process.env.QELOS_APP_URL! },
+    onTokenRefresh: async ({ req, res, newTokens, oldTokens }) => {
+      await sessionStore.rotate(req.sessionID, newTokens);
+    },
+  }),
+);
+```
+
+The hook receives `{ req, res, oldTokens, newTokens, sdk }`. Throwing aborts
+the in-flight request.
+
+### Manual cookie refresh
+
+Long-lived integrator-hosted sessions can also call the SDK directly to
+proactively refresh the cookie token (e.g. before a navigation that hands the
+session over to a downstream service):
+
+```ts
+const result = await req.qelos!.sdk.authentication.refreshCookieToken();
+// result.headers['set-cookie'] — fresh cookie value to forward
+// result.payload.user        — refreshed user
+```
+
+## Configuration
+
+```ts
+createQelosMiddleware({
+  config: {
+    appUrl: 'https://yourdomain.com', // required
+
+    // Service-to-service: use a static API token instead of cookies/refresh.
+    apiToken: process.env.QELOS_API_TOKEN,
+
+    // Cookie names. Defaults shown.
+    accessTokenCookie: 'q_access_token',
+    refreshTokenCookie: 'q_refresh_token',
+
+    // Reject anonymous requests with 401. Defaults to false.
+    requireAuth: false,
+
+    // Skip the middleware entirely for these path prefixes.
+    skipPaths: ['/health', '/metrics'],
+
+    // Anything you want passed through to the per-request SDK.
+    sdkOptions: {},
+  },
+
+  // Override workspace selection. Defaults to `workspaces[0]`.
+  resolveWorkspace: ({ req, user, workspaces }) => {
+    const headerId = req.headers['x-qelos-workspace'];
+    return workspaces.find((w) => w._id === headerId) || workspaces[0] || null;
+  },
+});
+```
+
+## TypeScript
+
+Importing from `@qelos/integrator-express` augments the Express `Request` type
+(via `declare module 'express'` and `declare module 'express-serve-static-core'`)
+so `req.qelos` is typed everywhere in your app. The shape is:
+
+```ts
+interface QelosRequestContext {
+  user: IUser | null;
+  workspace: IWorkspace | null;
+  workspaces: IWorkspace[];
+  sdk: QelosSDK;          // bound to the current request's tokens
+  tokens: QelosTokenPair; // mutated in place when a refresh occurs
+}
+```
+
+`req.qelos` is typed as non-optional. If you use `skipPaths`, the property is
+unset for skipped requests — guard with `if (req.qelos) { ... }` in those routes.
+
+## Requirements
+
+- Node.js >= 18 (uses the global `fetch`).
+- Express 4 or 5.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createQelosMiddleware, requireUser, } from './middleware';
+export type { CreateMiddlewareOptions, QelosMiddleware, } from './middleware';
+export { createRequestSdk } from './sdk-factory';
+export type { CreateSdkParams } from './sdk-factory';
+export type { QelosExpressConfig, QelosRequestContext, QelosTokenPair, ResolvedTokens, TokenRefreshContext, TokenRefreshHook, } from './types';
+export { completeSocialAuthCallback, applySocialAuthCookiesToServerResponse, getSocialAuthSetCookieParts, parseSocialCallbackRefreshToken, type SocialAuthCallbackPayload, type SocialCallbackInput, } from './social-auth';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSocialCallbackRefreshToken = exports.getSocialAuthSetCookieParts = exports.applySocialAuthCookiesToServerResponse = exports.completeSocialAuthCallback = exports.createRequestSdk = exports.requireUser = exports.createQelosMiddleware = void 0;
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "createQelosMiddleware", { enumerable: true, get: function () { return middleware_1.createQelosMiddleware; } });
+Object.defineProperty(exports, "requireUser", { enumerable: true, get: function () { return middleware_1.requireUser; } });
+var sdk_factory_1 = require("./sdk-factory");
+Object.defineProperty(exports, "createRequestSdk", { enumerable: true, get: function () { return sdk_factory_1.createRequestSdk; } });
+var social_auth_1 = require("./social-auth");
+Object.defineProperty(exports, "completeSocialAuthCallback", { enumerable: true, get: function () { return social_auth_1.completeSocialAuthCallback; } });
+Object.defineProperty(exports, "applySocialAuthCookiesToServerResponse", { enumerable: true, get: function () { return social_auth_1.applySocialAuthCookiesToServerResponse; } });
+Object.defineProperty(exports, "getSocialAuthSetCookieParts", { enumerable: true, get: function () { return social_auth_1.getSocialAuthSetCookieParts; } });
+Object.defineProperty(exports, "parseSocialCallbackRefreshToken", { enumerable: true, get: function () { return social_auth_1.parseSocialCallbackRefreshToken; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAGsB;AAFpB,mHAAA,qBAAqB,OAAA;AACrB,yGAAA,WAAW,OAAA;AAOb,6CAAiD;AAAxC,+GAAA,gBAAgB,OAAA;AAYzB,6CAOuB;AANrB,yHAAA,0BAA0B,OAAA;AAC1B,qIAAA,sCAAsC,OAAA;AACtC,0HAAA,2BAA2B,OAAA;AAC3B,8HAAA,+BAA+B,OAAA"}

package/dist/middleware.d.ts

@@ -0,0 +1,29 @@
+import type { Request, RequestHandler } from 'express';
+import type { IUser } from '@qelos/sdk/dist/authentication';
+import type { IWorkspace } from '@qelos/sdk/workspaces';
+import type { QelosExpressConfig, TokenRefreshHook } from './types';
+export interface CreateMiddlewareOptions {
+    config: QelosExpressConfig;
+    /**
+     * Hook invoked after a successful token refresh. The default implementation
+     * writes the new tokens back to the response cookies.
+     */
+    onTokenRefresh?: TokenRefreshHook;
+    /**
+     * Resolve the active workspace for a request. Defaults to picking the first
+     * workspace returned from `sdk.workspaces.getList()`.
+     */
+    resolveWorkspace?: (params: {
+        req: Request;
+        user: IUser;
+        workspaces: IWorkspace[];
+    }) => IWorkspace | null | Promise<IWorkspace | null>;
+}
+export declare function createQelosMiddleware(options: CreateMiddlewareOptions): RequestHandler;
+export type QelosMiddleware = ReturnType<typeof createQelosMiddleware>;
+/**
+ * Wrap a route handler so it only runs when `req.qelos.user` is populated.
+ * Otherwise responds with 401. Intended to be mounted *after*
+ * `createQelosMiddleware`.
+ */
+export declare function requireUser(handler: RequestHandler): RequestHandler;

package/dist/middleware.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createQelosMiddleware = createQelosMiddleware;
+exports.requireUser = requireUser;
+const sdk_factory_1 = require("./sdk-factory");
+const DEFAULT_ACCESS_COOKIE = 'q_access_token';
+const DEFAULT_REFRESH_COOKIE = 'q_refresh_token';
+function readCookie(req, name) {
+    // Prefer cookie-parser output when available.
+    const parsed = req.cookies;
+    if (parsed && typeof parsed[name] === 'string') {
+        return parsed[name];
+    }
+    const header = req.headers.cookie;
+    if (!header)
+        return undefined;
+    const prefix = name + '=';
+    for (const part of header.split(';')) {
+        const trimmed = part.trim();
+        if (trimmed.startsWith(prefix)) {
+            try {
+                return decodeURIComponent(trimmed.slice(prefix.length));
+            }
+            catch {
+                return trimmed.slice(prefix.length);
+            }
+        }
+    }
+    return undefined;
+}
+function readTokens(req, config) {
+    const accessCookie = config.accessTokenCookie || DEFAULT_ACCESS_COOKIE;
+    const refreshCookie = config.refreshTokenCookie || DEFAULT_REFRESH_COOKIE;
+    const cookieAccess = readCookie(req, accessCookie);
+    const cookieRefresh = readCookie(req, refreshCookie);
+    const authHeader = req.headers.authorization;
+    const headerAccess = authHeader && authHeader.toLowerCase().startsWith('bearer ')
+        ? authHeader.slice(7).trim()
+        : undefined;
+    return {
+        accessToken: headerAccess || cookieAccess || undefined,
+        refreshToken: cookieRefresh || undefined,
+    };
+}
+function serializeCookie(name, value, secure) {
+    const parts = [
+        `${name}=${encodeURIComponent(value)}`,
+        'Path=/',
+        'HttpOnly',
+        'SameSite=Lax',
+    ];
+    if (secure)
+        parts.push('Secure');
+    return parts.join('; ');
+}
+function appendSetCookie(res, value) {
+    const existing = res.getHeader('set-cookie');
+    if (Array.isArray(existing)) {
+        res.setHeader('set-cookie', [...existing, value]);
+    }
+    else if (typeof existing === 'string') {
+        res.setHeader('set-cookie', [existing, value]);
+    }
+    else {
+        res.setHeader('set-cookie', [value]);
+    }
+}
+function writeTokensToCookies(res, config, tokens) {
+    const accessCookie = config.accessTokenCookie || DEFAULT_ACCESS_COOKIE;
+    const refreshCookie = config.refreshTokenCookie || DEFAULT_REFRESH_COOKIE;
+    const secure = !/^http:\/\//i.test(config.appUrl);
+    const cookieRes = res;
+    if (typeof cookieRes.cookie === 'function') {
+        const cookieOptions = {
+            httpOnly: true,
+            secure,
+            sameSite: 'lax',
+            path: '/',
+        };
+        cookieRes.cookie(accessCookie, tokens.accessToken, cookieOptions);
+        if (tokens.refreshToken) {
+            cookieRes.cookie(refreshCookie, tokens.refreshToken, cookieOptions);
+        }
+        return;
+    }
+    appendSetCookie(res, serializeCookie(accessCookie, tokens.accessToken, secure));
+    if (tokens.refreshToken) {
+        appendSetCookie(res, serializeCookie(refreshCookie, tokens.refreshToken, secure));
+    }
+}
+function shouldSkip(req, config) {
+    if (!config.skipPaths?.length)
+        return false;
+    const path = req.path || req.url || '';
+    return config.skipPaths.some((prefix) => path.startsWith(prefix));
+}
+function createQelosMiddleware(options) {
+    const { config, resolveWorkspace } = options;
+    const onTokenRefresh = options.onTokenRefresh ||
+        (async ({ res, newTokens }) => {
+            writeTokensToCookies(res, config, newTokens);
+        });
+    return async function qelosMiddleware(req, res, next) {
+        if (shouldSkip(req, config)) {
+            next();
+            return;
+        }
+        const tokens = readTokens(req, config);
+        const sdk = (0, sdk_factory_1.createRequestSdk)({ config, tokens, req, res, onTokenRefresh });
+        const ctx = {
+            user: null,
+            workspace: null,
+            workspaces: [],
+            sdk,
+            tokens,
+        };
+        req.qelos = ctx;
+        const hasAuthMaterial = Boolean(config.apiToken || tokens.accessToken || tokens.refreshToken);
+        if (!hasAuthMaterial) {
+            if (config.requireAuth) {
+                res.status(401).json({ code: 'UNAUTHORIZED' });
+                return;
+            }
+            next();
+            return;
+        }
+        try {
+            ctx.user = await sdk.authentication.getLoggedInUser();
+        }
+        catch {
+            if (config.requireAuth) {
+                res.status(401).json({ code: 'UNAUTHORIZED' });
+                return;
+            }
+            next();
+            return;
+        }
+        try {
+            ctx.workspaces = await sdk.workspaces.getList();
+        }
+        catch {
+            ctx.workspaces = [];
+        }
+        if (ctx.user && ctx.workspaces.length) {
+            if (resolveWorkspace) {
+                ctx.workspace =
+                    (await resolveWorkspace({
+                        req,
+                        user: ctx.user,
+                        workspaces: ctx.workspaces,
+                    })) || null;
+            }
+            else {
+                ctx.workspace = ctx.workspaces[0] || null;
+            }
+        }
+        next();
+    };
+}
+/**
+ * Wrap a route handler so it only runs when `req.qelos.user` is populated.
+ * Otherwise responds with 401. Intended to be mounted *after*
+ * `createQelosMiddleware`.
+ */
+function requireUser(handler) {
+    return function qelosRequireUser(req, res, next) {
+        if (!req.qelos || !req.qelos.user) {
+            res.status(401).json({ code: 'UNAUTHORIZED' });
+            return;
+        }
+        return handler(req, res, next);
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/sdk-factory.d.ts

@@ -0,0 +1,16 @@
+import type { Request, Response } from 'express';
+import QelosSDK from '@qelos/sdk';
+import type { QelosExpressConfig, QelosTokenPair, TokenRefreshHook } from './types';
+export interface CreateSdkParams {
+    config: QelosExpressConfig;
+    /**
+     * Tokens for the current request. The factory mutates this object in place
+     * when a token refresh occurs, so callers can read the latest pair after
+     * the SDK has been used.
+     */
+    tokens: QelosTokenPair;
+    req: Request;
+    res: Response;
+    onTokenRefresh?: TokenRefreshHook;
+}
+export declare function createRequestSdk({ config, tokens, req, res, onTokenRefresh, }: CreateSdkParams): QelosSDK;

package/dist/sdk-factory.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestSdk = createRequestSdk;
+const sdk_1 = __importDefault(require("@qelos/sdk"));
+const NO_AUTH_URLS = new Set([
+    '/api/token/refresh',
+    '/api/cookie/refresh',
+    '/api/signin',
+    '/api/signup',
+]);
+function createRequestSdk({ config, tokens, req, res, onTokenRefresh, }) {
+    let sdk;
+    let refreshInFlight = null;
+    const baseOptions = config.sdkOptions || {};
+    async function performRefresh() {
+        if (!tokens.refreshToken && !tokens.accessToken) {
+            throw new Error('no refresh token available');
+        }
+        const previous = {
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+        };
+        let refreshed;
+        if (tokens.refreshToken) {
+            const result = await sdk.authentication.refreshToken(tokens.refreshToken);
+            refreshed = {
+                accessToken: result.payload.token,
+                refreshToken: result.payload.refreshToken,
+            };
+        }
+        else {
+            const result = await sdk.authentication.refreshCookieToken(tokens.accessToken);
+            refreshed = {
+                accessToken: result.payload.cookieToken,
+            };
+        }
+        tokens.accessToken = refreshed.accessToken;
+        tokens.refreshToken = refreshed.refreshToken;
+        if (onTokenRefresh) {
+            await onTokenRefresh({
+                req,
+                res,
+                oldTokens: previous,
+                newTokens: refreshed,
+                sdk,
+            });
+        }
+    }
+    function ensureRefresh() {
+        if (!refreshInFlight) {
+            refreshInFlight = performRefresh().finally(() => {
+                refreshInFlight = null;
+            });
+        }
+        return refreshInFlight;
+    }
+    const options = {
+        appUrl: config.appUrl,
+        fetch: globalThis.fetch,
+        forceRefresh: !config.apiToken,
+        ...baseOptions,
+    };
+    if (config.apiToken) {
+        options.apiToken = config.apiToken;
+    }
+    else {
+        if (tokens.accessToken) {
+            options.accessToken = tokens.accessToken;
+        }
+        if (tokens.refreshToken) {
+            options.refreshToken = tokens.refreshToken;
+        }
+        options.extraHeaders = async (relativeUrl, forceRefresh) => {
+            const headers = {};
+            if (NO_AUTH_URLS.has(relativeUrl)) {
+                return headers;
+            }
+            if (forceRefresh && tokens.refreshToken) {
+                await ensureRefresh();
+            }
+            const token = sdk?.authentication?.accessToken || tokens.accessToken;
+            if (token) {
+                headers.authorization = 'Bearer ' + token;
+            }
+            return headers;
+        };
+        options.onFailedRefreshToken = async () => {
+            await ensureRefresh();
+        };
+    }
+    sdk = new sdk_1.default(options);
+    return sdk;
+}
+//# sourceMappingURL=sdk-factory.js.map

package/dist/sdk-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-factory.js","sourceRoot":"","sources":["../src/sdk-factory.ts"],"names":[],"mappings":"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"}

package/dist/social-auth.d.ts

@@ -0,0 +1,10 @@
+import type QelosSDK from '@qelos/sdk';
+import type { SocialAuthCallbackPayload } from '@qelos/sdk';
+/**
+ * Runs {@link QelosSDK.authentication.socialCallback} for `requestUrl` and
+ * forwards session `Set-Cookie` headers to the Express response.
+ */
+export declare function completeSocialAuthCallback(sdk: QelosSDK, requestUrl: string, res: {
+    setHeader(name: string, value: string | string[]): void;
+}): Promise<SocialAuthCallbackPayload>;
+export { applySocialAuthCookiesToServerResponse, getSocialAuthSetCookieParts, parseSocialCallbackRefreshToken, type SocialAuthCallbackPayload, type SocialCallbackInput, } from '@qelos/sdk';

package/dist/social-auth.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSocialCallbackRefreshToken = exports.getSocialAuthSetCookieParts = exports.applySocialAuthCookiesToServerResponse = void 0;
+exports.completeSocialAuthCallback = completeSocialAuthCallback;
+const sdk_1 = require("@qelos/sdk");
+/**
+ * Runs {@link QelosSDK.authentication.socialCallback} for `requestUrl` and
+ * forwards session `Set-Cookie` headers to the Express response.
+ */
+async function completeSocialAuthCallback(sdk, requestUrl, res) {
+    const result = await sdk.authentication.socialCallback(requestUrl);
+    (0, sdk_1.applySocialAuthCookiesToServerResponse)(res, result);
+    return result;
+}
+var sdk_2 = require("@qelos/sdk");
+Object.defineProperty(exports, "applySocialAuthCookiesToServerResponse", { enumerable: true, get: function () { return sdk_2.applySocialAuthCookiesToServerResponse; } });
+Object.defineProperty(exports, "getSocialAuthSetCookieParts", { enumerable: true, get: function () { return sdk_2.getSocialAuthSetCookieParts; } });
+Object.defineProperty(exports, "parseSocialCallbackRefreshToken", { enumerable: true, get: function () { return sdk_2.parseSocialCallbackRefreshToken; } });
+//# sourceMappingURL=social-auth.js.map

package/dist/social-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"social-auth.js","sourceRoot":"","sources":["../src/social-auth.ts"],"names":[],"mappings":";;;AAQA,gEAQC;AAdD,oCAAoE;AAEpE;;;GAGG;AACI,KAAK,UAAU,0BAA0B,CAC9C,GAAa,EACb,UAAkB,EAClB,GAAgE;IAEhE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IACnE,IAAA,4CAAsC,EAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kCAMoB;AALlB,6HAAA,sCAAsC,OAAA;AACtC,kHAAA,2BAA2B,OAAA;AAC3B,sHAAA,+BAA+B,OAAA"}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+import type { Request, Response } from 'express';
+import type QelosSDK from '@qelos/sdk';
+import type { IUser } from '@qelos/sdk/dist/authentication';
+import type { IWorkspace } from '@qelos/sdk/workspaces';
+import type { QelosSDKOptions } from '@qelos/sdk/types';
+import type { QelosConfig, QelosContext, QelosTokenPair, ResolvedTokens } from '@qelos/global-types';
+export type { QelosTokenPair, ResolvedTokens } from '@qelos/global-types';
+export interface QelosExpressConfig extends QelosConfig {
+    /**
+     * Optional extra options merged into the per-request SDK instance.
+     */
+    sdkOptions?: Partial<QelosSDKOptions>;
+}
+export interface TokenRefreshContext {
+    req: Request;
+    res: Response;
+    oldTokens: QelosTokenPair;
+    newTokens: ResolvedTokens;
+    sdk: QelosSDK;
+}
+export type TokenRefreshHook = (ctx: TokenRefreshContext) => void | Promise<void>;
+export type QelosRequestContext = QelosContext<QelosSDK, IUser, IWorkspace>;
+declare module 'express' {
+    interface Request {
+        qelos: QelosRequestContext;
+    }
+}
+declare module 'express-serve-static-core' {
+    interface Request {
+        qelos: QelosRequestContext;
+    }
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@qelos/integrator-express",
+  "version": "4.0.0",
+  "description": "Express middleware that identifies the Qelos user and active workspace before your route handlers run",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "require": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "qelos",
+    "express",
+    "middleware",
+    "integrator",
+    "auth"
+  ],
+  "author": "David Meir-Levy <davidmeirlevy@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "express": "^4.17.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@qelos/global-types": "^4.0.0",
+    "@qelos/sdk": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/express-serve-static-core": "^4.19.6",
+    "express": "^4.21.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "build": "tsc",
+    "pre-build": "tsc",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  }
+}