@qelos/sdk 4.1.1 → 4.2.1

package/dist/mcp-auth.js

@@ -0,0 +1,216 @@
+function readQueryValue(input, key) {
+    const raw = input[key];
+    if (Array.isArray(raw)) {
+        return raw[0] && typeof raw[0] === 'string' ? raw[0] : undefined;
+    }
+    return typeof raw === 'string' ? raw : undefined;
+}
+function searchParamsFromString(input) {
+    try {
+        const url = new URL(input);
+        if (url.search) {
+            return url.searchParams;
+        }
+        if (url.hash.length > 1) {
+            return new URLSearchParams(url.hash.slice(1));
+        }
+        return url.searchParams;
+    }
+    catch {
+        const trimmed = input.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        const queryPart = trimmed.startsWith('?')
+            ? trimmed.slice(1)
+            : trimmed.startsWith('#')
+                ? trimmed.slice(1)
+                : trimmed.includes('=')
+                    ? trimmed
+                    : undefined;
+        return queryPart ? new URLSearchParams(queryPart) : undefined;
+    }
+}
+function searchParamsFromInput(input) {
+    if (input instanceof URLSearchParams) {
+        return input;
+    }
+    if (input instanceof URL) {
+        if (input.search.length > 1) {
+            return input.searchParams;
+        }
+        if (input.hash.length > 1) {
+            return new URLSearchParams(input.hash.slice(1));
+        }
+        return input.searchParams;
+    }
+    if (typeof input === 'string') {
+        return searchParamsFromString(input);
+    }
+    const params = new URLSearchParams();
+    const code = readQueryValue(input, 'code');
+    const state = readQueryValue(input, 'state');
+    const error = readQueryValue(input, 'error');
+    const errorDescription = readQueryValue(input, 'error_description');
+    if (code)
+        params.set('code', code);
+    if (state)
+        params.set('state', state);
+    if (error)
+        params.set('error', error);
+    if (errorDescription)
+        params.set('error_description', errorDescription);
+    return params.toString() ? params : undefined;
+}
+/**
+ * Parse authorization callback parameters from an MCP OAuth redirect.
+ * Accepts a full URL, {@link URL}, `URLSearchParams`, a query/fragment string,
+ * or a query object such as `req.query` from Next.js or Express.
+ */
+export function parseMcpCallbackParams(input) {
+    const params = searchParamsFromInput(input);
+    if (!params) {
+        return {};
+    }
+    const result = {};
+    const code = params.get('code');
+    const state = params.get('state');
+    const error = params.get('error');
+    const errorDescription = params.get('error_description');
+    if (code)
+        result.code = code;
+    if (state)
+        result.state = state;
+    if (error)
+        result.error = error;
+    if (errorDescription)
+        result.errorDescription = errorDescription;
+    return result;
+}
+/** Relative authorize path with query string for {@link QlAuthentication.getMcpAuthorizeUrl}. */
+export function buildMcpAuthorizePath(options) {
+    const search = new URLSearchParams({ redirect_uri: options.redirectUri });
+    if (options.state)
+        search.set('state', options.state);
+    if (options.codeChallenge)
+        search.set('code_challenge', options.codeChallenge);
+    if (options.codeChallengeMethod)
+        search.set('code_challenge_method', options.codeChallengeMethod);
+    if (options.clientId)
+        search.set('client_id', options.clientId);
+    return `/api/auth/mcp/authorize?${search.toString()}`;
+}
+/**
+ * Build `/api/auth/mcp/authorize?…` from OAuth authorize query params
+ * (e.g. when `/mcp/authorize` receives a direct client redirect).
+ */
+export function buildMcpAuthorizePathFromQuery(query) {
+    const redirectUri = readQueryValue(query, 'redirect_uri');
+    if (!redirectUri) {
+        return null;
+    }
+    const options = { redirectUri };
+    const state = readQueryValue(query, 'state');
+    const codeChallenge = readQueryValue(query, 'code_challenge');
+    const codeChallengeMethod = readQueryValue(query, 'code_challenge_method');
+    const clientId = readQueryValue(query, 'client_id');
+    if (state)
+        options.state = state;
+    if (codeChallenge)
+        options.codeChallenge = codeChallenge;
+    if (codeChallengeMethod)
+        options.codeChallengeMethod = codeChallengeMethod;
+    if (clientId)
+        options.clientId = clientId;
+    return buildMcpAuthorizePath(options);
+}
+/** Login redirect used by Qelos after an unauthenticated MCP authorize request. */
+export function buildMcpLoginRedirectUrl(authorizePath, options) {
+    const loginPath = options?.loginPath ?? '/login';
+    return `${loginPath}?redirect=${encodeURIComponent(authorizePath)}`;
+}
+/** Consent page URL issued after the user signs in during MCP OAuth. */
+export function buildMcpConsentPageUrl(mcpState, options) {
+    const consentPath = options?.consentPath ?? '/mcp/authorize';
+    return `${consentPath}?mcp_state=${encodeURIComponent(mcpState)}`;
+}
+/**
+ * Resolve the post-login redirect target from login-page query params.
+ * Matches the resume logic used by the Qelos admin login flow.
+ */
+export function resolveMcpLoginRedirect(query, options) {
+    const redirect = readQueryValue(query, 'redirect');
+    if (redirect) {
+        return redirect;
+    }
+    const mcpState = readQueryValue(query, 'mcp_state');
+    if (mcpState) {
+        return buildMcpConsentPageUrl(mcpState, options);
+    }
+    return buildMcpAuthorizePathFromQuery(query);
+}
+/** Redirect URI with `error=access_denied` for MCP consent denial. */
+export function appendMcpAccessDeniedRedirect(redirectUri, oauthState) {
+    try {
+        const url = new URL(redirectUri);
+        url.searchParams.set('error', 'access_denied');
+        if (oauthState) {
+            url.searchParams.set('state', oauthState);
+        }
+        return url.toString();
+    }
+    catch {
+        const separator = redirectUri.includes('?') ? '&' : '?';
+        let result = `${redirectUri}${separator}error=access_denied`;
+        if (oauthState) {
+            result += `&state=${encodeURIComponent(oauthState)}`;
+        }
+        return result;
+    }
+}
+/**
+ * Decode the signed `mcp_state` JWT payload for display on a consent page.
+ * Does not verify the signature — use only for UI labels, not authorization.
+ */
+export function decodeMcpOAuthStatePayload(mcpState) {
+    if (!mcpState) {
+        return null;
+    }
+    try {
+        const parts = mcpState.split('.');
+        if (parts.length !== 3 || !parts[1]) {
+            return null;
+        }
+        const base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof globalThis.atob === 'function'
+            ? globalThis.atob(base64)
+            : Buffer.from(base64, 'base64').toString('utf8');
+        const decoded = JSON.parse(json);
+        const payload = {};
+        if (decoded.ru)
+            payload.redirectUri = decoded.ru;
+        if (decoded.s)
+            payload.state = decoded.s;
+        if (decoded.cc)
+            payload.codeChallenge = decoded.cc;
+        if (decoded.ccm)
+            payload.codeChallengeMethod = decoded.ccm;
+        if (decoded.t)
+            payload.tenant = decoded.t;
+        if (decoded.cid)
+            payload.clientId = decoded.cid;
+        return payload.redirectUri ? payload : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildMcpTokenExchangeBody(options) {
+    return new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: options.code,
+        redirect_uri: options.redirectUri,
+        code_verifier: options.codeVerifier,
+    });
+}
+//# sourceMappingURL=mcp-auth.js.map

package/dist/mcp-auth.js.map

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

package/dist/payments.d.ts

@@ -1,6 +1,6 @@
 import { QelosSDKOptions } from './types';
 import BaseSDK from './base-sdk';
-import { IPlan, ISubscription, IInvoice, ICoupon, BillingCycle } from '@qelos/global-types';
+import { IPlan, ISubscription, IInvoice, ICoupon, BillingCycle, CheckoutCustomer } from '@qelos/global-types';
 export interface CheckoutRequest {
     /** Required when not providing `subscriptionId`. Must be a non-dynamic plan. */
     planId?: string;
@@ -9,6 +9,17 @@ export interface CheckoutRequest {
     couponCode?: string;
     successUrl?: string;
     cancelUrl?: string;
+    /**
+     * Real-world identity of the billable entity. Passed through to the payment
+     * provider (e.g. Sumit) so it can create a properly-named customer record
+     * instead of falling back to the raw billable entity ID.
+     */
+    customer?: CheckoutCustomer;
+    /**
+     * When true, cancels any existing active or trialing subscription for the
+     * authenticated billable entity before starting checkout (e.g. plan change).
+     */
+    reset?: boolean;
     /**
      * Pre-created subscription ID. Required for dynamic plans — the admin must set
      * `dynamicAmount` on the subscription before this checkout call will succeed.

package/dist/payments.js.map

@@ -1 +1 @@
-{"version":3,"file":"payments.js","sourceRoot":"","sources":["../src/payments.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,YAAY,CAAC;AA2BjC,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,OAAO;IACrC,YAAY,GAAG,MAAM,CAAC;IAE9B,YAAY,OAAwB;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;IAED,QAAQ,CAAC,KAA8B;QACrC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,eAAe,CAAC,KAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC,WAAW,CAAU,GAAG,IAAI,CAAC,YAAY,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,OAAO,IAAI,CAAC,WAAW,CAAQ,GAAG,IAAI,CAAC,YAAY,UAAU,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,MAAc,EAAE,YAA0B,EAAE,UAAmB;QAC7E,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,gBAAgB,EACpC;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;SAC3D,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAuB;QAC9B,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,WAAW,EAC/B;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CACF,CAAC;IACJ,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,WAAW,CAAgB,GAAG,IAAI,CAAC,YAAY,mBAAmB,CAAC,CAAC;IAClF,CAAC;IAED,kBAAkB,CAAC,cAAsB;QACvC,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,kBAAkB,cAAc,SAAS,EAC7D,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAC;IACJ,CAAC;IAED,WAAW,CAAC,KAA2B;QACrC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,eAAe,CAAC,KAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC,WAAW,CAAa,GAAG,IAAI,CAAC,YAAY,YAAY,EAAE,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAW,GAAG,IAAI,CAAC,YAAY,aAAa,SAAS,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,cAAc,CAAC,IAAY,EAAE,MAAe;QAC1C,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,mBAAmB,EACvC;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACvC,CACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"payments.js","sourceRoot":"","sources":["../src/payments.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,YAAY,CAAC;AAsCjC,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,OAAO;IACrC,YAAY,GAAG,MAAM,CAAC;IAE9B,YAAY,OAAwB;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;IAED,QAAQ,CAAC,KAA8B;QACrC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,eAAe,CAAC,KAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC,WAAW,CAAU,GAAG,IAAI,CAAC,YAAY,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,OAAO,IAAI,CAAC,WAAW,CAAQ,GAAG,IAAI,CAAC,YAAY,UAAU,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,MAAc,EAAE,YAA0B,EAAE,UAAmB;QAC7E,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,gBAAgB,EACpC;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;SAC3D,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAuB;QAC9B,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,WAAW,EAC/B;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CACF,CAAC;IACJ,CAAC;IAED,iBAAiB;QACf,OAAO,IAAI,CAAC,WAAW,CAAgB,GAAG,IAAI,CAAC,YAAY,mBAAmB,CAAC,CAAC;IAClF,CAAC;IAED,kBAAkB,CAAC,cAAsB;QACvC,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,kBAAkB,cAAc,SAAS,EAC7D,EAAE,MAAM,EAAE,KAAK,EAAE,CAClB,CAAC;IACJ,CAAC;IAED,WAAW,CAAC,KAA2B;QACrC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,eAAe,CAAC,KAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC,WAAW,CAAa,GAAG,IAAI,CAAC,YAAY,YAAY,EAAE,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAW,GAAG,IAAI,CAAC,YAAY,aAAa,SAAS,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,cAAc,CAAC,IAAY,EAAE,MAAe;QAC1C,OAAO,IAAI,CAAC,WAAW,CACrB,GAAG,IAAI,CAAC,YAAY,mBAAmB,EACvC;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACvC,CACF,CAAC;IACJ,CAAC;CACF"}

package/docs/payments.md

@@ -104,6 +104,60 @@ const result = await adminSdk.payments.checkout({
 
 ---
 
+## Payments configuration
+
+Admin-only tenant settings stored in `payments-configuration`.
+
+### `GET /api/payments/configuration`
+
+Returns the current payments configuration metadata. **Auth**: privileged.
+
+**Response `200`**
+
+```json
+{
+  "key": "payments-configuration",
+  "metadata": {
+    "isEnabled": true,
+    "paymentSourceId": "integration-source-id",
+    "defaultCurrency": "ILS",
+    "gracePeriodDays": 3,
+    "successUrl": "https://your-app.com/billing/return?status=success",
+    "cancelUrl": "https://your-app.com/billing/return?status=cancel"
+  }
+}
+```
+
+### `PUT /api/payments/configuration`
+
+Creates or updates payments configuration. Partial `metadata` is merged with the existing record. **Auth**: privileged.
+
+**Body**
+
+```json
+{
+  "metadata": {
+    "isEnabled": true,
+    "paymentSourceId": "integration-source-id",
+    "successUrl": "https://your-app.com/billing/return?status=success",
+    "cancelUrl": "https://your-app.com/billing/return?status=cancel"
+  }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `isEnabled` | boolean | Enable payments for the tenant |
+| `paymentSourceId` | string | Integration source `_id` for the payment provider |
+| `defaultCurrency` | string | Default ISO 4217 currency code |
+| `gracePeriodDays` | number | Grace period after failed payment |
+| `successUrl` | string | Default redirect URL after successful checkout |
+| `cancelUrl` | string | Default redirect URL when checkout is canceled |
+
+> **SDK:** `adminSdk.payments.getPaymentsConfiguration()` · `adminSdk.payments.updatePaymentsConfiguration(metadata)`
+
+---
+
 ## Listing Plans and Subscriptions
 
 ### User SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/sdk",
-  "version": "4.1.1",
+  "version": "4.2.1",
   "description": "SDK for Qelos API",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -96,23 +96,23 @@
     },
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "test": "node --import tsx --test **/**/*.test.ts",
+    "type-check": "tsc --noEmit",
+    "build": "npm run type-check && tsc",
+    "pre-build": "pnpm run type-check && tsc"
+  },
   "author": "David Meir-Levy <davidmeirlevy@gmail.com>",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@qelos/global-types": "^4.1.1"
+    "@qelos/global-types": "workspace:^"
   },
   "devDependencies": {
     "tsx": "^4.21.0",
     "typescript": "^4.9.5"
   },
-  "gitHead": "13468bc51557291935b96b1aeaa837b8b52861e8",
-  "scripts": {
-    "test": "node --import tsx --test **/**/*.test.ts",
-    "type-check": "tsc --noEmit",
-    "build": "npm run type-check && tsc",
-    "pre-build": "pnpm run type-check && tsc"
-  }
-}
+  "gitHead": "13468bc51557291935b96b1aeaa837b8b52861e8"
+}

package/src/administrator/integration-sources.ts

@@ -1,6 +1,10 @@
 import { QelosSDKOptions, RequestExtra } from '../types';
 import BaseSDK from '../base-sdk';
-import { IIntegrationSource } from '@qelos/global-types';
+import {
+  IIntegrationSource,
+  IIntegrationSourceStatusRequest,
+  IIntegrationSourceStatusResult,
+} from '@qelos/global-types';
 
 export default class QlIntegrationSources extends BaseSDK {
   private relativePath = '/api/integration-sources';
@@ -40,4 +44,29 @@ export default class QlIntegrationSources extends BaseSDK {
     })
   }
 
+  checkStatus(
+    sourceId: string,
+    overrides?: Partial<Pick<IIntegrationSource, 'metadata' | 'authentication'>>,
+  ): Promise<IIntegrationSourceStatusResult> {
+    return this.callJsonApi<IIntegrationSourceStatusResult>(
+      `${this.relativePath}/${sourceId}/status`,
+      {
+        method: 'post',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(overrides ?? {}),
+      },
+    );
+  }
+
+  checkDraftStatus(source: IIntegrationSourceStatusRequest): Promise<IIntegrationSourceStatusResult> {
+    return this.callJsonApi<IIntegrationSourceStatusResult>(
+      `${this.relativePath}/status`,
+      {
+        method: 'post',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(source),
+      },
+    );
+  }
+
 }

package/src/administrator/integrations.ts

@@ -38,6 +38,7 @@ export default class QlIntegrations extends BaseSDK {
     trigger?: any;
     target?: any;
     dataManipulation?: any;
+    targetManipulation?: any;
   }): Promise<IIntegration> {
     return this.callJsonApi<IIntegration>(
       `${this.relativePath}/${integrationId}`,
@@ -53,6 +54,7 @@ export default class QlIntegrations extends BaseSDK {
     trigger: any;
     target: any;
     dataManipulation?: any;
+    targetManipulation?: any;
     active?: boolean;
   }): Promise<IIntegration> {
     return this.callJsonApi<IIntegration>(this.relativePath, {

package/src/administrator/payments.ts

@@ -3,8 +3,14 @@ import BaseSDK from '../base-sdk';
 import {
   IPlan, ISubscription, IInvoice, ICoupon,
   BillableEntityType, SubscriptionStatus, InvoiceStatus, BillingCycle,
+  IPaymentsConfigurationMetadata, CheckoutCustomer,
 } from '@qelos/global-types';
 
+export interface PaymentsConfigurationRecord {
+  key: string;
+  metadata: IPaymentsConfigurationMetadata;
+}
+
 export interface AdminCheckoutRequest {
   planId: string;
   billingCycle: BillingCycle;
@@ -14,12 +20,20 @@ export interface AdminCheckoutRequest {
   couponCode?: string;
   successUrl?: string;
   cancelUrl?: string;
+  /** When true, cancels any existing active/trialing subscription before checkout. */
+  reset?: boolean;
   /**
    * Admin-only. For plans with `dynamic: true`, sets the `dynamicAmount` on the
    * pending subscription before initiating checkout. Regular users cannot set this;
    * use `setSubscriptionDynamicAmount()` + a separate `checkout()` call instead.
    */
   amount?: number;
+  /**
+   * Real-world identity of the billable entity. Passed through to the payment
+   * provider (e.g. Sumit) so it can create a properly-named customer record
+   * instead of falling back to the raw billable entity ID.
+   */
+  customer?: CheckoutCustomer;
 }
 
 export interface CreateSubscriptionData {
@@ -181,4 +195,18 @@ export default class QlPaymentsAdmin extends BaseSDK {
   deleteCoupon(couponId: string) {
     return this.callJsonApi<ICoupon>(`/api/coupons/${couponId}`, { method: 'delete' });
   }
+
+  /** Load tenant payments settings (`payments-configuration`). */
+  getPaymentsConfiguration() {
+    return this.callJsonApi<PaymentsConfigurationRecord>('/api/payments/configuration');
+  }
+
+  /** Update tenant payments settings. Partial metadata is merged with the existing record. */
+  updatePaymentsConfiguration(metadata: Partial<IPaymentsConfigurationMetadata>) {
+    return this.callJsonApi<PaymentsConfigurationRecord>('/api/payments/configuration', {
+      method: 'put',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ metadata }),
+    });
+  }
 }

package/src/administrator/tests/integration-sources-status.test.ts

@@ -0,0 +1,121 @@
+import * as assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { IntegrationSourceKind } from '@qelos/global-types';
+import { QelosSDKOptions } from '../../types';
+import QlIntegrationSources from '../integration-sources';
+
+function jsonResponse(body: unknown) {
+  const res = new Response(JSON.stringify(body));
+  res.headers.set('Content-Type', 'application/json');
+  return res;
+}
+
+const connectedResult = {
+  status: 'connected' as const,
+  message: 'Connection verified',
+  kind: IntegrationSourceKind.Sumit,
+  checkedAt: '2026-07-23T05:00:00.000Z',
+};
+
+test('QlIntegrationSources status methods', async (t) => {
+  await t.test('checkStatus sends POST to saved source status path', async () => {
+    let url = '';
+    let init: RequestInit | undefined;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (requestUrl, requestInit) => {
+        url = requestUrl.toString();
+        init = requestInit;
+        return jsonResponse(connectedResult);
+      },
+    };
+
+    const sdk = new QlIntegrationSources(options);
+    const result = await sdk.checkStatus('src-123');
+
+    assert.equal(url, 'http://localhost:3000/api/integration-sources/src-123/status');
+    assert.equal(init?.method, 'post');
+    assert.equal((init?.headers as Record<string, string>)['content-type'], 'application/json');
+    assert.deepEqual(JSON.parse(init?.body as string), {});
+    assert.deepEqual(result, connectedResult);
+  });
+
+  await t.test('checkStatus sends metadata and authentication overrides', async () => {
+    let init: RequestInit | undefined;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        init = requestInit;
+        return jsonResponse(connectedResult);
+      },
+    };
+
+    const sdk = new QlIntegrationSources(options);
+    await sdk.checkStatus('src-123', {
+      metadata: { companyId: '42' },
+      authentication: { apiKey: 'secret' },
+    });
+
+    assert.deepEqual(JSON.parse(init?.body as string), {
+      metadata: { companyId: '42' },
+      authentication: { apiKey: 'secret' },
+    });
+  });
+
+  await t.test('checkDraftStatus sends POST to draft status path', async () => {
+    let url = '';
+    let init: RequestInit | undefined;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (requestUrl, requestInit) => {
+        url = requestUrl.toString();
+        init = requestInit;
+        return jsonResponse(connectedResult);
+      },
+    };
+
+    const draft = {
+      kind: IntegrationSourceKind.PayPal,
+      metadata: { environment: 'sandbox' },
+      authentication: { clientId: 'id', clientSecret: 'secret' },
+    };
+
+    const sdk = new QlIntegrationSources(options);
+    const result = await sdk.checkDraftStatus(draft);
+
+    assert.equal(url, 'http://localhost:3000/api/integration-sources/status');
+    assert.equal(init?.method, 'post');
+    assert.equal((init?.headers as Record<string, string>)['content-type'], 'application/json');
+    assert.deepEqual(JSON.parse(init?.body as string), draft);
+    assert.deepEqual(result, connectedResult);
+  });
+
+  await t.test('checkDraftStatus is kind-agnostic and works for non-payment sources too', async () => {
+    let init: RequestInit | undefined;
+    const emailConnectedResult = {
+      status: 'connected' as const,
+      message: 'SMTP connection verified',
+      kind: IntegrationSourceKind.Email,
+      checkedAt: '2026-07-23T05:00:00.000Z',
+    };
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        init = requestInit;
+        return jsonResponse(emailConnectedResult);
+      },
+    };
+
+    const draft = {
+      kind: IntegrationSourceKind.Email,
+      metadata: { smtp: 'smtp.example.com', username: 'bot@example.com', email: 'bot@example.com', pop3: 'pop3.example.com', senderName: 'Bot' },
+      authentication: { password: 'secret' },
+    };
+
+    const sdk = new QlIntegrationSources(options);
+    const result = await sdk.checkDraftStatus(draft);
+
+    assert.deepEqual(JSON.parse(init?.body as string), draft);
+    assert.deepEqual(result, emailConnectedResult);
+  });
+});

package/src/authentication.ts

@@ -1,6 +1,26 @@
 import { QelosSDKOptions } from './types';
 import BaseSDK from './base-sdk';
 import { decodeMeUser } from './services/decode-uri-fields';
+import {
+  buildMcpAuthorizePath,
+  buildMcpTokenExchangeBody,
+  type McpAuthorizeOptions,
+  type McpOAuthTokenResponse,
+  type McpTokenExchangeOptions,
+  type McpTokenExchangeResult,
+} from './mcp-auth';
+
+export type {
+  McpAuthorizeOptions,
+  McpCallbackInput,
+  McpCallbackParams,
+  McpTokenExchangeOptions,
+  McpTokenExchangeResult,
+  DecodedMcpOAuthStatePayload,
+  McpPagePathOptions,
+} from './mcp-auth';
+
+export { parseMcpCallbackParams } from './mcp-auth';
 
 export interface IUser {
   _id: string;
@@ -376,6 +396,50 @@ export default class QlAuthentication extends BaseSDK {
     return this.exchangeAuthCallback(refreshToken);
   }
 
+  getMcpAuthorizeUrl(options: McpAuthorizeOptions): string {
+    if (!options.redirectUri) {
+      throw new Error('redirectUri is required');
+    }
+    return this.buildUrl(buildMcpAuthorizePath(options));
+  }
+
+  async exchangeMcpAuthorizationCode(options: McpTokenExchangeOptions): Promise<McpTokenExchangeResult> {
+    const { code, redirectUri, codeVerifier } = options;
+    if (!code || !redirectUri || !codeVerifier) {
+      throw new Error('code, redirectUri, and codeVerifier are required');
+    }
+
+    const res = await this.callApi('/api/auth/mcp/token', {
+      method: 'post',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: buildMcpTokenExchangeBody(options).toString(),
+    });
+
+    if (!res.ok) {
+      let detail = '';
+      try {
+        detail = (await res.text()).slice(0, 512);
+      } catch {
+        /* ignore */
+      }
+      throw new Error(
+        `failed to exchange MCP authorization code: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`,
+      );
+    }
+
+    const body = (await res.json()) as McpOAuthTokenResponse;
+    this.#accessToken = body.access_token;
+    this.#refreshToken = body.refresh_token;
+
+    const user = await this.getLoggedInUser();
+    return {
+      accessToken: body.access_token,
+      refreshToken: body.refresh_token,
+      expiresIn: body.expires_in,
+      user,
+    };
+  }
+
   getLoggedInUser() {
     return this.callJsonApi<IUser>('/api/me').then(decodeMeUser);
   }