@qelos/global-types 4.1.1 → 4.2.1

package/dist/payment-event-resolution.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENTS_DOCS_BASE_URL = void 0;
+exports.resolvePaymentEventDocsUrl = resolvePaymentEventDocsUrl;
+exports.sanitizeProviderErrorBody = sanitizeProviderErrorBody;
+exports.extractSumitProviderError = extractSumitProviderError;
+exports.resolvePaymentProviderPublicContext = resolvePaymentProviderPublicContext;
+exports.appendPaymentProviderContext = appendPaymentProviderContext;
+exports.buildPaymentAdminSuggestions = buildPaymentAdminSuggestions;
+exports.buildPaymentEventDescription = buildPaymentEventDescription;
+exports.PAYMENTS_DOCS_BASE_URL = 'https://docs.qelos.io/payments';
+const TROUBLESHOOTING_ERROR_CODES = new Set([
+    'PAYMENTS_NOT_CONFIGURED',
+    'ACTIVE_SUBSCRIPTION_EXISTS',
+    'DYNAMIC_AMOUNT_NOT_SET',
+    'DYNAMIC_PLAN_REQUIRES_SUBSCRIPTION',
+    'DYNAMIC_PLAN_UNSUPPORTED_PROVIDER',
+    'MISSING_REDIRECT_URLS',
+    'INVALID_CHECKOUT_AMOUNT',
+    'INVALID_SUMIT_COMPANY_ID',
+    'MISSING_SUMIT_CREDENTIALS',
+    'UNSUPPORTED_SUMIT_CURRENCY',
+    'INTEGRATION_SOURCE_NOT_FOUND',
+    'MISSING_EXTERNAL_PRICE_ID',
+    'PLAN_NOT_ACTIVE',
+    'SUBSCRIPTION_NOT_PENDING',
+    'INVALID_SIGNATURE',
+    'WEBHOOK_SECRET_NOT_CONFIGURED',
+    'TENANT_NOT_FOUND',
+]);
+function troubleshootingCodeAnchor(code) {
+    return code.toLowerCase().replace(/_/g, '-');
+}
+function resolveProviderEventDocsUrl(providerKind, eventName) {
+    const provider = providerKind.toLowerCase();
+    if (eventName === 'payment-method-save-failed') {
+        return `${exports.PAYMENTS_DOCS_BASE_URL}/events#failed-credit-card-capture-payment-method-save-failed`;
+    }
+    if (eventName === 'payment-failed' || eventName === 'webhook-processing-failed') {
+        return `${exports.PAYMENTS_DOCS_BASE_URL}/events#${provider}-troubleshooting`;
+    }
+    if (eventName === 'checkout-failed' || eventName === 'provider-call-failed') {
+        switch (provider) {
+            case 'sumit':
+                return `${exports.PAYMENTS_DOCS_BASE_URL}/events#checkout-initiation-failure-checkout-failed-or-provider-call-failed`;
+            case 'paddle':
+                return `${exports.PAYMENTS_DOCS_BASE_URL}/events#checkout-validation-failure-checkout-failed`;
+            case 'paypal':
+                return `${exports.PAYMENTS_DOCS_BASE_URL}/events#checkout-and-subscription-setup-failure-checkout-failed-or-provider-call-failed`;
+            case 'dodopayments':
+                return `${exports.PAYMENTS_DOCS_BASE_URL}/events#checkout-failure-checkout-failed-or-provider-call-failed`;
+            default:
+                break;
+        }
+    }
+    switch (provider) {
+        case 'sumit':
+            return `${exports.PAYMENTS_DOCS_BASE_URL}/events#sumit-troubleshooting`;
+        case 'paddle':
+            return `${exports.PAYMENTS_DOCS_BASE_URL}/events#paddle-troubleshooting`;
+        case 'paypal':
+            return `${exports.PAYMENTS_DOCS_BASE_URL}/events#paypal-troubleshooting`;
+        case 'dodopayments':
+            return `${exports.PAYMENTS_DOCS_BASE_URL}/events#dodopayments-troubleshooting`;
+        default:
+            return `${exports.PAYMENTS_DOCS_BASE_URL}/troubleshooting`;
+    }
+}
+function resolvePaymentEventDocsUrl(context) {
+    const code = context.code?.toUpperCase();
+    if (code && TROUBLESHOOTING_ERROR_CODES.has(code)) {
+        return `${exports.PAYMENTS_DOCS_BASE_URL}/troubleshooting#${troubleshootingCodeAnchor(code)}`;
+    }
+    if (context.providerKind) {
+        return resolveProviderEventDocsUrl(context.providerKind, context.eventName);
+    }
+    return `${exports.PAYMENTS_DOCS_BASE_URL}/troubleshooting`;
+}
+function pushUnique(suggestions, suggestion) {
+    if (suggestions.some((s) => s.summary === suggestion.summary)) {
+        return;
+    }
+    suggestions.push(suggestion);
+}
+function sumitCredentialsSuggestions(suggestions, message, providerError) {
+    const combined = [
+        message,
+        providerError?.UserErrorMessage,
+        providerError?.TechnicalErrorDetails,
+    ]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase();
+    if (combined.includes('credential')
+        || combined.includes('apikey')
+        || combined.includes('api key')
+        || combined.includes('companyid')
+        || combined.includes('company id')
+        || combined.includes('unauthorized')
+        || combined.includes('authentication')) {
+        pushUnique(suggestions, {
+            summary: 'Verify Sumit API credentials',
+            action: 'Open Admin → Integrations → Sumit, confirm Company ID matches https://app.sumit.co.il/developers/keys/ and re-save a freshly generated API key.',
+        });
+    }
+}
+function sanitizeProviderErrorBody(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const sanitized = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+        const normalized = key.replace(/[_-]/g, '').toLowerCase();
+        if (normalized === 'credentials'
+            || normalized === 'apikey'
+            || normalized === 'companyid'
+            || normalized === 'singleusetoken'
+            || normalized === 'cardnumber'
+            || normalized === 'creditcardnumber'
+            || normalized === 'cvv'
+            || normalized === 'cvc'
+            || normalized === 'password'
+            || normalized === 'secret') {
+            continue;
+        }
+        sanitized[key] = nestedValue;
+    }
+    return sanitized;
+}
+function extractSumitProviderError(responseBody) {
+    const sanitized = sanitizeProviderErrorBody(responseBody);
+    if (!sanitized) {
+        return null;
+    }
+    if (sanitized.providerError && typeof sanitized.providerError === 'object') {
+        return sanitizeProviderErrorBody(sanitized.providerError);
+    }
+    if (sanitized.UserErrorMessage
+        || sanitized.TechnicalErrorDetails
+        || sanitized.Status) {
+        return sanitized;
+    }
+    if (sanitized.Data && typeof sanitized.Data === 'object') {
+        return sanitizeProviderErrorBody(sanitized.Data);
+    }
+    return sanitized;
+}
+function resolvePaymentProviderPublicContext(providerKind, metadata, providerSourceId) {
+    const context = {};
+    if (providerSourceId) {
+        context.providerSourceId = providerSourceId;
+    }
+    if (!providerKind || !metadata) {
+        return context;
+    }
+    switch (providerKind) {
+        case 'sumit':
+            if (metadata.companyId != null && metadata.companyId !== '') {
+                context.providerPublicAccountId = String(metadata.companyId);
+            }
+            break;
+        case 'paypal':
+            if (typeof metadata.clientId === 'string' && metadata.clientId) {
+                context.providerPublicAccountId = metadata.clientId;
+            }
+            if (typeof metadata.environment === 'string' && metadata.environment) {
+                context.providerEnvironment = metadata.environment;
+            }
+            break;
+        case 'paddle':
+            if (typeof metadata.environment === 'string' && metadata.environment) {
+                context.providerEnvironment = metadata.environment;
+            }
+            break;
+        case 'dodopayments':
+            if (typeof metadata.environment === 'string' && metadata.environment) {
+                context.providerEnvironment = metadata.environment;
+            }
+            break;
+        default:
+            break;
+    }
+    return context;
+}
+function appendPaymentProviderContext(metadata, providerContext) {
+    if (!providerContext) {
+        return metadata;
+    }
+    return {
+        ...metadata,
+        ...(providerContext.providerSourceId ? { providerSourceId: providerContext.providerSourceId } : {}),
+        ...(providerContext.providerPublicAccountId ? { providerPublicAccountId: providerContext.providerPublicAccountId } : {}),
+        ...(providerContext.providerEnvironment ? { providerEnvironment: providerContext.providerEnvironment } : {}),
+    };
+}
+function buildPaymentAdminSuggestions(context) {
+    const suggestions = [];
+    const code = context.code?.toUpperCase();
+    const message = context.message?.toLowerCase() || '';
+    const providerError = context.providerError;
+    if (code === 'PAYMENTS_NOT_CONFIGURED') {
+        pushUnique(suggestions, {
+            summary: 'Configure payments for this tenant',
+            action: 'Open Admin → Pricing Plans → Configuration, enable payments, and select a payment provider integration source.',
+        });
+    }
+    if (code === 'ACTIVE_SUBSCRIPTION_EXISTS') {
+        pushUnique(suggestions, {
+            summary: 'Cancel the existing subscription before checkout',
+            action: 'The billable entity already has an active or trialing subscription. Cancel it with sdk.payments.cancelSubscription(existingSubscriptionId), or pass reset: true on checkout to cancel automatically and start a new subscription.',
+        });
+    }
+    if (code === 'DYNAMIC_AMOUNT_NOT_SET') {
+        pushUnique(suggestions, {
+            summary: 'Set the subscription amount before checkout',
+            action: 'This plan is dynamic-priced. An admin must set dynamicAmount on the pending subscription before the user can pay.',
+        });
+    }
+    if (code === 'DYNAMIC_PLAN_REQUIRES_SUBSCRIPTION' || code === 'DYNAMIC_PLAN_UNSUPPORTED_PROVIDER') {
+        pushUnique(suggestions, {
+            summary: 'Use the dynamic-plan checkout flow',
+            action: 'Create a pending subscription first, set dynamicAmount (admin), then call checkout with subscriptionId. Dynamic plans require Sumit.',
+        });
+    }
+    if (code === 'MISSING_REDIRECT_URLS') {
+        pushUnique(suggestions, {
+            summary: 'Configure checkout redirect URLs',
+            action: 'Add successUrl and cancelUrl in Admin → Pricing Plans → Configuration, or pass them in the checkout request.',
+        });
+    }
+    if (code === 'INVALID_CHECKOUT_AMOUNT') {
+        pushUnique(suggestions, {
+            summary: 'Set a positive checkout amount',
+            action: 'For dynamic plans, an admin must set dynamicAmount on the pending subscription before checkout. Static plans need a non-zero monthly/yearly price.',
+        });
+    }
+    if (code === 'INVALID_SUMIT_COMPANY_ID' || code === 'MISSING_SUMIT_CREDENTIALS') {
+        pushUnique(suggestions, {
+            summary: 'Fix Sumit Company ID',
+            action: 'Open Admin → Integrations → Sumit and enter the numeric Company ID from https://app.sumit.co.il/developers/keys/.',
+        });
+    }
+    if (code === 'UNSUPPORTED_SUMIT_CURRENCY') {
+        pushUnique(suggestions, {
+            summary: 'Use a Sumit-supported plan currency',
+            action: 'Change the plan currency to ILS, USD, or EUR. Sumit does not support other currencies.',
+        });
+    }
+    if (code === 'INTEGRATION_SOURCE_NOT_FOUND') {
+        pushUnique(suggestions, {
+            summary: 'Reconnect the payment provider',
+            action: 'The configured paymentSourceId no longer exists. Re-select the Sumit integration in Admin → Pricing Plans → Configuration.',
+        });
+    }
+    if (context.providerKind === 'sumit') {
+        sumitCredentialsSuggestions(suggestions, context.message, providerError);
+        if (context.operation === 'beginCheckoutRedirect') {
+            pushUnique(suggestions, {
+                summary: 'Confirm Sumit hosted checkout is enabled',
+                action: 'In the Sumit account, verify redirect/hosted checkout is enabled for the merchant and that the API key has billing permissions.',
+            });
+        }
+        if (message.includes('unsupported sumit currency')) {
+            pushUnique(suggestions, {
+                summary: 'Use a Sumit-supported plan currency',
+                action: 'Set the plan currency to ILS, USD, or EUR before retrying checkout.',
+            });
+        }
+        if (message.includes('missing api key or company id')) {
+            pushUnique(suggestions, {
+                summary: 'Complete the Sumit integration credentials',
+                action: 'Open Admin → Integrations → Sumit and save both Company ID and API key.',
+            });
+        }
+    }
+    if (context.status === 401
+        || context.status === 403
+        || message.includes('401')
+        || message.includes('403')) {
+        pushUnique(suggestions, {
+            summary: 'Payment provider rejected the credentials',
+            action: 'Regenerate the provider API key/secret in the provider dashboard and update the integration source in Admin → Integrations.',
+        });
+    }
+    if (code === 'INTEGRATION_TARGET_FAILED'
+        && suggestions.length === 0
+        && context.providerKind === 'sumit') {
+        pushUnique(suggestions, {
+            summary: 'Review Sumit account configuration',
+            action: 'Verify Company ID and API key in Admin → Integrations → Sumit, then retry checkout. If it still fails, check Sumit developer logs for the rejected beginredirect request.',
+        });
+    }
+    return suggestions;
+}
+function buildPaymentEventDescription(baseDescription, providerError) {
+    const userMessage = providerError?.UserErrorMessage;
+    if (typeof userMessage === 'string' && userMessage.trim()) {
+        return `${baseDescription}: ${userMessage.trim()}`;
+    }
+    return baseDescription;
+}
+//# sourceMappingURL=payment-event-resolution.js.map

package/dist/payment-event-resolution.js.map

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

package/dist/payments.d.ts

@@ -0,0 +1,165 @@
+/** Determines whether billing is tied to individual users (B2C) or workspaces (B2B). */
+export type BillableEntityType = 'user' | 'workspace';
+/** Lifecycle states of a subscription. */
+export type SubscriptionStatus = 'pending' | 'active' | 'canceled' | 'past_due' | 'trialing' | 'expired';
+/** Supported billing intervals. */
+export type BillingCycle = 'monthly' | 'yearly';
+/** Payment status of an invoice. */
+export type InvoiceStatus = 'paid' | 'pending' | 'failed' | 'refunded';
+/** Type of discount a coupon provides. */
+export type CouponDiscountType = 'percentage' | 'fixed';
+/**
+ * Real-world identity of the billable entity, passed through checkout so payment
+ * providers (e.g. Sumit) can create a properly-named customer record instead of
+ * falling back to the raw billable entity ID.
+ */
+export interface CheckoutCustomer {
+    name?: string;
+    /** Legal/invoice name, e.g. a company name distinct from the contact's personal name. */
+    nameForInvoice?: string;
+    email?: string;
+    phone?: string;
+    address?: string;
+    city?: string;
+    /** Company tax/VAT identifier. */
+    taxId?: string;
+}
+/** Tenant payments settings stored in the `payments-configuration` configuration key. */
+export interface IPaymentsConfigurationMetadata {
+    isEnabled?: boolean;
+    /** Integration source `_id` (admin UI field name). */
+    paymentSourceId?: string;
+    /** Same as `paymentSourceId`; normalized by the payments service when loading config. */
+    providerSourceId?: string;
+    providerKind?: 'paddle' | 'paypal' | 'sumit' | 'dodopayments' | string;
+    defaultCurrency?: string;
+    gracePeriodDays?: number;
+    /** Default redirect URL after successful checkout (required for Sumit unless overridden per checkout). */
+    successUrl?: string;
+    /** Default redirect URL when the user cancels checkout (required for Sumit unless overridden per checkout). */
+    cancelUrl?: string;
+    webhookSecret?: string;
+}
+/**
+ * Arbitrary limits associated with a plan (e.g. max users, storage quota).
+ * Keys are limit names; values can be numbers, booleans, or strings.
+ */
+export interface IPlanLimits {
+    [key: string]: number | boolean | string;
+}
+/**
+ * Maps payment provider kinds to their external product/price identifiers.
+ * Used to link internal plans to provider-specific entities.
+ */
+export interface IPlanExternalIds {
+    [providerKind: string]: {
+        productId?: string;
+        monthlyPriceId?: string;
+        yearlyPriceId?: string;
+    };
+}
+/** A pricing plan that users or workspaces can subscribe to. */
+export interface IPlan {
+    _id?: string;
+    /** Tenant identifier for multi-tenant isolation. */
+    tenant: string;
+    name: string;
+    description?: string;
+    /** Human-readable feature descriptions displayed on pricing pages. */
+    features: string[];
+    monthlyPrice: number;
+    yearlyPrice: number;
+    /** ISO 4217 currency code (e.g. "USD", "EUR"). */
+    currency: string;
+    isActive: boolean;
+    /** Controls display order — lower numbers appear first. */
+    sortOrder: number;
+    /**
+     * When `true`, the price is not fixed — it is calculated at checkout time
+     * (e.g. per-user, per-item, or otherwise variable). `monthlyPrice` /
+     * `yearlyPrice` are ignored for dynamic plans; the caller must supply an
+     * `amount` at checkout instead.
+     */
+    dynamic?: boolean;
+    limits?: IPlanLimits;
+    externalIds?: IPlanExternalIds;
+    metadata?: Record<string, any>;
+    created?: Date;
+}
+/** A subscription linking a billable entity to a plan. */
+export interface ISubscription {
+    _id?: string;
+    tenant: string;
+    /** Reference to the subscribed plan. */
+    planId: string;
+    billableEntityType: BillableEntityType;
+    billableEntityId: string;
+    status: SubscriptionStatus;
+    billingCycle: BillingCycle;
+    currentPeriodStart?: Date;
+    currentPeriodEnd?: Date;
+    /** Provider-side subscription identifier for reconciliation. */
+    externalSubscriptionId?: string;
+    /** Integration source ID used for this subscription's provider calls. */
+    providerId?: string;
+    /** Payment provider kind (e.g. "paddle", "paypal", "sumit"). */
+    providerKind?: string;
+    couponId?: string;
+    /**
+     * Admin-configured charge amount for dynamic-priced plans. Only admins may
+     * set this field; it is read by the checkout service when `IPlan.dynamic` is
+     * `true`. Must be set before checkout can proceed on a dynamic plan.
+     */
+    dynamicAmount?: number;
+    metadata?: Record<string, any>;
+    created?: Date;
+}
+/** A single line item within an invoice. */
+export interface IInvoiceItem {
+    description: string;
+    amount: number;
+    quantity: number;
+}
+/** An invoice record for a payment event. */
+export interface IInvoice {
+    _id?: string;
+    tenant: string;
+    subscriptionId?: string;
+    billableEntityType: BillableEntityType;
+    billableEntityId: string;
+    amount: number;
+    /** ISO 4217 currency code. */
+    currency: string;
+    status: InvoiceStatus;
+    /** Provider-side invoice identifier. */
+    externalInvoiceId?: string;
+    providerKind?: string;
+    /** URL to download/view the invoice from the provider. */
+    invoiceUrl?: string;
+    paidAt?: Date;
+    periodStart?: Date;
+    periodEnd?: Date;
+    items: IInvoiceItem[];
+    created?: Date;
+}
+/** A discount coupon that can be applied during checkout. */
+export interface ICoupon {
+    _id?: string;
+    tenant: string;
+    /** Unique coupon code entered by users. */
+    code: string;
+    discountType: CouponDiscountType;
+    /** For percentage: 0–100. For fixed: absolute amount in the coupon's currency. */
+    discountValue: number;
+    /** ISO 4217 currency code — relevant for fixed-amount discounts. */
+    currency?: string;
+    /** `null` or `undefined` means unlimited redemptions. */
+    maxRedemptions?: number;
+    currentRedemptions: number;
+    validFrom?: Date;
+    validUntil?: Date;
+    /** Empty array means the coupon applies to all plans. */
+    applicablePlanIds: string[];
+    isActive: boolean;
+    created?: Date;
+}

package/dist/payments.js

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

package/dist/payments.js.map

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

package/dist/plugin-crud.d.ts

@@ -0,0 +1,11 @@
+export interface IPluginCrud {
+    name: string;
+    display: {
+        name: string;
+        plural: string;
+        capitalized: string;
+        capitalizedPlural: string;
+    };
+    identifierKey: string;
+    schema: any;
+}

package/dist/plugin-crud.js

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

package/dist/plugin-crud.js.map

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

package/dist/plugin.d.ts

@@ -0,0 +1,30 @@
+import { IMicroFrontend } from './micro-frontend';
+import { IEventSubscriber } from './event-subscriber';
+import { IPluginCrud } from './plugin-crud';
+import { IInjectable } from './injectable';
+import { INavbarGroup } from './navbar-group';
+export interface IPlugin {
+    tenant: string;
+    name: string;
+    description?: string;
+    apiPath: string;
+    registerUrl: string;
+    user: string;
+    token: string;
+    proxyUrl: string;
+    authAcquire: {
+        refreshTokenUrl: string;
+        refreshTokenKey: string;
+        accessTokenKey: string;
+    };
+    auth: {
+        refreshTokenIdentifier?: string;
+    };
+    manifestUrl: string;
+    callbackUrl?: string;
+    subscribedEvents: IEventSubscriber[];
+    microFrontends: IMicroFrontend[];
+    cruds: IPluginCrud[];
+    injectables: IInjectable[];
+    navBarGroups?: INavbarGroup[];
+}

package/dist/plugin.js

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

package/dist/plugin.js.map

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

package/dist/qelos-integrator.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared contracts every Qelos framework integrator (`@qelos/integrator-*`)
+ * builds upon. Defined here — rather than in each integrator — so the
+ * per-request shape and configuration surface are guaranteed identical across
+ * frameworks.
+ *
+ * `@qelos/sdk` depends on `@qelos/global-types`, so this file deliberately
+ * avoids importing from the SDK; instead, {@link QelosContext} is generic over
+ * the SDK instance type and integrators specialize it with the concrete
+ * `QelosSDK` / `IUser` / `IWorkspace` types from `@qelos/sdk`.
+ */
+/**
+ * Tokens read from an inbound request. Integrators mutate this object in place
+ * when a refresh occurs so later code can read the current pair.
+ */
+export interface QelosTokenPair {
+    accessToken?: string;
+    refreshToken?: string;
+}
+/**
+ * Result of a successful token refresh.
+ */
+export interface ResolvedTokens {
+    accessToken: string;
+    refreshToken?: string;
+}
+/**
+ * Minimal user contract shared by all integrators. The SDK's `IUser` (rich,
+ * with first/last name, metadata, etc.) is assignable to this and is what
+ * integrators actually plug in via the `TUser` parameter on
+ * {@link QelosContext}.
+ */
+export interface IQelosUser {
+    _id: string;
+    username: string;
+    email: string;
+    roles: string[];
+    [key: string]: any;
+}
+/**
+ * Minimal workspace contract shared by all integrators. The SDK's `IWorkspace`
+ * is assignable to this.
+ */
+export interface IQelosWorkspace {
+    name: string;
+    [key: string]: any;
+}
+/**
+ * Base configuration contract every framework integrator builds upon.
+ * Framework-specific configs (e.g. `QelosExpressConfig`, `QelosNextConfig`)
+ * extend this with transport-specific options such as `sdkOptions`.
+ */
+export interface QelosConfig {
+    /**
+     * Base URL of the Qelos backend (e.g. https://yourdomain.com).
+     */
+    appUrl: string;
+    /**
+     * Static API token used for service-to-service calls. When provided, no
+     * cookie/refresh-token handling is performed.
+     */
+    apiToken?: string;
+    /**
+     * Cookie name carrying the Qelos access token. Defaults to `q_access_token`.
+     */
+    accessTokenCookie?: string;
+    /**
+     * Cookie name carrying the Qelos refresh token. Defaults to `q_refresh_token`.
+     */
+    refreshTokenCookie?: string;
+    /**
+     * If true, the integrator rejects requests (401) when the user cannot be
+     * resolved. Defaults to `false` — anonymous requests pass through with
+     * `qelos.user = null`.
+     */
+    requireAuth?: boolean;
+    /**
+     * Skip the integrator entirely for requests whose path starts with any of
+     * these prefixes. Useful for `/health`, `/_next`, `/api/_auth`, etc.
+     */
+    skipPaths?: string[];
+}
+/**
+ * Per-request Qelos context every integrator produces. Generic over the SDK
+ * instance type and the user/workspace shape so framework integrators narrow
+ * these to the SDK's concrete types (`QelosSDK`, `IUser`, `IWorkspace`)
+ * without dragging the SDK into `@qelos/global-types`.
+ */
+export interface QelosContext<TSdk = unknown, TUser extends IQelosUser = IQelosUser, TWorkspace extends IQelosWorkspace = IQelosWorkspace> {
+    /**
+     * The authenticated user, or `null` when anonymous.
+     */
+    user: TUser | null;
+    /**
+     * The active workspace for the request, or `null` when none is active /
+     * the user is anonymous.
+     */
+    workspace: TWorkspace | null;
+    /**
+     * The full list of workspaces the user has access to.
+     */
+    workspaces: TWorkspace[];
+    /**
+     * SDK instance bound to the current request's tokens.
+     */
+    sdk: TSdk;
+    /**
+     * Tokens read from the request. Mutated in place when a refresh occurs so
+     * later code can read the current pair.
+     */
+    tokens: QelosTokenPair;
+}