@mercuryo-ai/magicpay-sdk 0.1.0-test.2

package/dist/secret-flow.js

@@ -0,0 +1,536 @@
+import { claimRemoteSecret, createRemoteSecretRequest, getRemoteSecretRequest, getRemoteSessionSecretCatalog, } from './session-client.js';
+import { getMagicPayErrorCode, isMagicPayAbortError, MagicPayRequestError, isMagicPayRequestErrorStatus, } from './gateway.js';
+export const LOGIN_FIELD_KEYS = ['username', 'password'];
+export const IDENTITY_FIELD_KEYS = [
+    'full_name',
+    'document_number',
+    'date_of_birth',
+    'nationality',
+    'issue_date',
+    'expiry_date',
+    'issuing_country',
+];
+export const PAYMENT_CARD_FIELD_KEYS = [
+    'cardholder',
+    'pan',
+    'exp_month',
+    'exp_year',
+    'cvv',
+];
+export const PROTECTED_BINDING_VALUE_HINTS = [
+    'direct',
+    'full_name.given',
+    'full_name.family',
+    'date_of_birth.day',
+    'date_of_birth.month',
+    'date_of_birth.year',
+];
+function toSecretRequestHintFields(fieldKeys) {
+    return fieldKeys.map((key) => ({ key }));
+}
+function resolveSecretRequestHintFields(hint) {
+    if (hint.fields.length === 0) {
+        return [];
+    }
+    const firstField = hint.fields[0];
+    if (typeof firstField === 'string') {
+        return toSecretRequestHintFields(hint.fields);
+    }
+    return hint.fields;
+}
+const SECRET_REQUEST_NOT_FULFILLED_CODES = ['secret_request_not_fulfilled'];
+const SECRET_REQUEST_ALREADY_CLAIMED_CODES = ['secret_request_already_claimed'];
+const SECRET_REQUEST_NOT_FULFILLED_MESSAGES = [
+    'This secret request is not approved yet.',
+    'This secret request does not have usable secret values.',
+    'This secret request does not have resolved secret values yet.',
+    'secret_request_not_fulfilled',
+];
+const SECRET_REQUEST_ALREADY_CLAIMED_MESSAGES = [
+    'A secret payload was already claimed for this request.',
+    'This secret request is already claimed.',
+    'secret_request_already_claimed',
+];
+function formatUnknownSdkError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object') {
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return Object.prototype.toString.call(error);
+        }
+    }
+    return String(error);
+}
+function formatAbortReason(error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return error.message;
+    }
+    return 'MagicPay request processing was aborted by the caller.';
+}
+function isTerminalSecretRequestStatus(status) {
+    return status !== 'pending';
+}
+function isTransientPollFailure(outcome) {
+    if (outcome.kind === 'not_found' || outcome.kind === 'aborted') {
+        return false;
+    }
+    return (outcome.status === undefined ||
+        outcome.status === 0 ||
+        outcome.status === 408 ||
+        outcome.status === 429 ||
+        outcome.status === 502 ||
+        outcome.status === 503 ||
+        outcome.status === 504 ||
+        outcome.errorCode === 'request_timeout');
+}
+async function waitForNextPoll(delayMs, signal) {
+    if (delayMs <= 0) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new DOMException('This operation was aborted', 'AbortError');
+        }
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            clearTimeout(timeoutId);
+            signal?.removeEventListener('abort', onAbort);
+            reject(signal?.reason ?? new DOMException('This operation was aborted', 'AbortError'));
+        };
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function fulfilledReasonForType(type) {
+    return type === 'secret_read'
+        ? 'MagicPay approved access to the saved secret values for this request.'
+        : 'The user supplied the requested secret values for this request.';
+}
+export function describeSecretRequestStatus(status, requestType) {
+    switch (status) {
+        case 'pending':
+            return {
+                outcomeType: 'approval_pending',
+                message: 'Protected secret request is waiting for user approval.',
+                reason: 'MagicPay has not approved this secret request yet.',
+                nextAction: 'poll-secret',
+            };
+        case 'fulfilled':
+            return {
+                message: 'Protected secret request is approved and ready to fill.',
+                reason: fulfilledReasonForType(requestType),
+                nextAction: 'fill-secret',
+            };
+        case 'denied':
+            return {
+                outcomeType: 'approval_denied',
+                message: 'Protected secret request was denied and cannot be used.',
+                reason: 'MagicPay reports that the user denied this protected request.',
+                nextAction: 'ask-user',
+            };
+        case 'expired':
+            return {
+                outcomeType: 'request_expired',
+                message: 'Protected secret request is no longer usable.',
+                reason: 'MagicPay reports that this secret request expired before it could be claimed.',
+                nextAction: 'request-secret',
+            };
+        case 'failed':
+            return {
+                message: 'Protected secret request failed and cannot be used.',
+                reason: 'MagicPay reports that this secret request failed before it could be claimed.',
+                nextAction: 'request-secret',
+            };
+        case 'canceled':
+            return {
+                message: 'Protected secret request was canceled and cannot be used.',
+                reason: 'MagicPay reports that this secret request was canceled before it could be claimed.',
+                nextAction: 'request-secret',
+            };
+    }
+}
+export function evaluateSecretRequestForFill(request, options) {
+    if (request.fillRef !== options.fillRef) {
+        return {
+            kind: 'fill_mismatch',
+            requestFillRef: request.fillRef,
+        };
+    }
+    if (request.claimedAt) {
+        return {
+            kind: 'already_claimed',
+            claimedAt: request.claimedAt,
+        };
+    }
+    if (request.status !== 'fulfilled') {
+        return {
+            kind: 'not_ready',
+            statusContract: describeSecretRequestStatus(request.status, request.requestType),
+        };
+    }
+    const mismatchReasons = [];
+    if (request.host && options.observedHost && request.host !== options.observedHost) {
+        mismatchReasons.push('host');
+    }
+    if (request.scopeRef && request.scopeRef !== options.observedScopeRef) {
+        mismatchReasons.push('scope');
+    }
+    if (mismatchReasons.length > 0) {
+        return {
+            kind: 'context_mismatch',
+            mismatchReasons,
+            ...(request.host ? { expectedHost: request.host } : {}),
+            ...(options.observedHost ? { observedHost: options.observedHost } : {}),
+            ...(request.scopeRef ? { expectedScopeRef: request.scopeRef } : {}),
+            ...(options.observedScopeRef ? { observedScopeRef: options.observedScopeRef } : {}),
+        };
+    }
+    return { kind: 'ready' };
+}
+function normalizeCatalogLookupValue(value) {
+    return value.trim().replace(/\.+$/, '').toLowerCase();
+}
+function asJsonRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+function pickFirstString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function mapRemoteSessionState(response) {
+    return {
+        sessionId: response.session.id,
+        status: response.session.status,
+        currentRequestId: response.current_request?.id ?? null,
+        lastEventSeq: response.session.last_event_seq,
+        browserSessionId: response.browser_session_id,
+    };
+}
+export function mapSessionRequestToSecretRequestSnapshot(request) {
+    const payload = asJsonRecord(request.payload);
+    const storedSecret = asJsonRecord(payload.stored_secret);
+    return {
+        requestId: request.id,
+        fillRef: pickFirstString(payload, ['fill_ref', 'fillRef']) ?? '',
+        requestType: request.type === 'secret_write' ? 'secret_write' : 'secret_read',
+        status: request.status,
+        storedSecretRef: pickFirstString(payload, ['stored_secret_ref', 'storedSecretRef']) ??
+            pickFirstString(storedSecret, ['id']),
+        kind: payload.kind === 'login' || payload.kind === 'identity' || payload.kind === 'payment_card'
+            ? payload.kind
+            : undefined,
+        host: pickFirstString(payload, ['host']),
+        pageRef: pickFirstString(asJsonRecord(payload.page), ['ref']),
+        scopeRef: pickFirstString(payload, ['scope_ref', 'scopeRef']),
+        createdAt: request.created_at,
+        updatedAt: request.updated_at,
+        ...(request.expires_at ? { expiresAt: request.expires_at } : {}),
+        ...(request.resolved_at ? { resolvedAt: request.resolved_at } : {}),
+    };
+}
+export function mapClaimedRemoteSecret(response) {
+    return {
+        requestId: response.request_id,
+        issuedAt: response.issued_at,
+        expiresAt: response.expires_at ?? undefined,
+        secret: {
+            values: { ...response.secret.values },
+            source: response.secret.source,
+            storedSecretRef: response.secret.stored_secret_ref ?? undefined,
+            credentialId: response.secret.credential_id ?? undefined,
+            kind: response.secret.kind ?? undefined,
+        },
+    };
+}
+function toStoredSecretFieldKeys(fields) {
+    return fields
+        .map((field) => field.key)
+        .filter((fieldKey) => [
+        'username',
+        'password',
+        'full_name',
+        'document_number',
+        'date_of_birth',
+        'nationality',
+        'issue_date',
+        'expiry_date',
+        'issuing_country',
+        'cardholder',
+        'pan',
+        'exp_month',
+        'exp_year',
+        'cvv',
+    ].includes(fieldKey));
+}
+export function mapApiCatalogEntryToStoredSecret(entry, host) {
+    return {
+        storedSecretRef: entry.id,
+        kind: entry.kind,
+        scope: entry.applicability.mode === 'global' ? 'global' : 'site',
+        displayName: entry.display_name,
+        fieldKeys: toStoredSecretFieldKeys(entry.fields),
+        intentRequired: true,
+        applicability: entry.applicability.mode === 'global'
+            ? { target: 'global' }
+            : { target: 'host', value: host },
+    };
+}
+export function resolveCatalogHost(urlOrHost) {
+    const trimmed = urlOrHost.trim();
+    if (trimmed.length === 0) {
+        throw new Error('secret_catalog_host_required');
+    }
+    try {
+        const parsed = new URL(trimmed);
+        if (!parsed.hostname) {
+            throw new Error('missing_hostname');
+        }
+        return normalizeCatalogLookupValue(parsed.hostname);
+    }
+    catch {
+        return normalizeCatalogLookupValue(trimmed);
+    }
+}
+export function resolveSecretCatalogContext(catalogByHost, urlOrHost) {
+    const host = resolveCatalogHost(urlOrHost);
+    return {
+        host,
+        catalog: catalogByHost?.[host] ?? null,
+    };
+}
+export async function fetchSecretCatalog(gateway, sessionId, urlOrHost, options = {}) {
+    const host = resolveCatalogHost(urlOrHost);
+    const entries = await getRemoteSessionSecretCatalog(gateway, sessionId, host, options);
+    return {
+        host,
+        syncedAt: options.syncedAt ?? new Date().toISOString(),
+        storedSecrets: entries.map((entry) => mapApiCatalogEntryToStoredSecret(entry, host)),
+    };
+}
+export async function createSecretRequest(gateway, input, options = {}) {
+    const response = await createRemoteSecretRequest(gateway, input.sessionId, {
+        clientRequestId: input.clientRequestId,
+        fillRef: input.fillRef,
+        purpose: input.purpose,
+        merchantName: input.merchantName,
+        ...(input.page ? { page: input.page } : {}),
+        secretHint: {
+            ...(input.secretHint.storedSecretRef
+                ? { storedSecretRef: input.secretHint.storedSecretRef }
+                : {}),
+            ...(input.secretHint.credentialKey
+                ? { credentialKey: input.secretHint.credentialKey }
+                : {}),
+            ...(input.secretHint.credentialName
+                ? { credentialName: input.secretHint.credentialName }
+                : {}),
+            ...(input.secretHint.kind ? { kind: input.secretHint.kind } : {}),
+            ...(input.secretHint.host ? { host: input.secretHint.host } : {}),
+            ...(input.secretHint.scopeRef ? { scopeRef: input.secretHint.scopeRef } : {}),
+            fields: resolveSecretRequestHintFields(input.secretHint),
+        },
+        ...(input.run ? { run: input.run } : {}),
+        ...(input.step ? { step: input.step } : {}),
+    }, options);
+    return {
+        requestId: response.request.id,
+        snapshot: mapSessionRequestToSecretRequestSnapshot(response.request),
+        reused: response.reused,
+        duplicate: response.duplicate,
+        session: mapRemoteSessionState(response),
+    };
+}
+export async function pollSecretRequest(gateway, sessionId, requestId, options = {}) {
+    try {
+        const response = await getRemoteSecretRequest(gateway, sessionId, requestId, options);
+        return {
+            success: true,
+            result: {
+                requestId: response.request.id,
+                snapshot: mapSessionRequestToSecretRequestSnapshot(response.request),
+                session: mapRemoteSessionState(response),
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            kind: isMagicPayAbortError(error)
+                ? 'aborted'
+                : isMagicPayRequestErrorStatus(error, 404)
+                    ? 'not_found'
+                    : 'other',
+            reason: isMagicPayAbortError(error)
+                ? formatAbortReason(error)
+                : isMagicPayRequestErrorStatus(error, 404)
+                    ? 'MagicPay did not return a secret request for the provided session ID and request ID.'
+                    : formatUnknownSdkError(error),
+            ...(error instanceof MagicPayRequestError ? { status: error.status } : {}),
+            ...(error instanceof MagicPayRequestError ? { errorCode: error.errorCode } : {}),
+        };
+    }
+}
+export async function pollSecretRequestUntil(gateway, sessionId, requestId, options = {}) {
+    const startedAt = Date.now();
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    const maxIntervalMs = options.maxIntervalMs ?? 30_000;
+    const backoffMultiplier = options.backoffMultiplier ?? 1.2;
+    let nextIntervalMs = options.intervalMs ?? 10_000;
+    let attempts = 0;
+    let lastResult;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new RangeError('MagicPay pollUntil timeout must be a finite non-negative number.');
+    }
+    if (!Number.isFinite(nextIntervalMs) || nextIntervalMs < 0) {
+        throw new RangeError('MagicPay pollUntil interval must be a finite non-negative number.');
+    }
+    if (!Number.isFinite(maxIntervalMs) || maxIntervalMs < 0) {
+        throw new RangeError('MagicPay pollUntil max interval must be a finite non-negative number.');
+    }
+    if (!Number.isFinite(backoffMultiplier) || backoffMultiplier < 1) {
+        throw new RangeError('MagicPay pollUntil backoff multiplier must be a finite number >= 1.');
+    }
+    while (true) {
+        if (options.signal?.aborted) {
+            return {
+                success: false,
+                requestId,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+                kind: 'aborted',
+                reason: formatAbortReason(options.signal.reason),
+                ...(lastResult ? { lastResult } : {}),
+            };
+        }
+        attempts += 1;
+        const outcome = await pollSecretRequest(gateway, sessionId, requestId, {
+            fetchImpl: options.fetchImpl,
+            signal: options.signal,
+            timeoutMs: options.requestTimeoutMs,
+        });
+        const elapsedMs = Date.now() - startedAt;
+        options.onAttempt?.({
+            attempt: attempts,
+            elapsedMs,
+            nextIntervalMs,
+            outcome,
+        });
+        if (outcome.success) {
+            lastResult = outcome.result;
+            const statusContract = describeSecretRequestStatus(outcome.result.snapshot.status, outcome.result.snapshot.requestType);
+            const stopWhen = options.stopWhen ?? 'terminal';
+            const shouldStop = stopWhen === 'fulfilled'
+                ? outcome.result.snapshot.status === 'fulfilled'
+                : isTerminalSecretRequestStatus(outcome.result.snapshot.status);
+            if (shouldStop) {
+                return {
+                    success: true,
+                    requestId: outcome.result.requestId,
+                    attempts,
+                    elapsedMs,
+                    result: outcome.result,
+                    statusContract,
+                };
+            }
+        }
+        else {
+            const shouldRetry = outcome.kind !== 'aborted' &&
+                options.retryOnTransientFailure !== false &&
+                isTransientPollFailure(outcome);
+            if (!shouldRetry) {
+                return {
+                    success: false,
+                    requestId,
+                    attempts,
+                    elapsedMs,
+                    kind: outcome.kind,
+                    reason: outcome.reason,
+                    ...(lastResult ? { lastResult } : {}),
+                    ...(outcome.status !== undefined ? { status: outcome.status } : {}),
+                    ...(outcome.errorCode !== undefined ? { errorCode: outcome.errorCode } : {}),
+                };
+            }
+        }
+        if (elapsedMs >= timeoutMs) {
+            return {
+                success: false,
+                requestId,
+                attempts,
+                elapsedMs,
+                kind: 'timeout',
+                reason: `MagicPay secret request polling timed out after ${timeoutMs}ms.`,
+                ...(lastResult ? { lastResult } : {}),
+            };
+        }
+        const remainingMs = Math.max(0, timeoutMs - elapsedMs);
+        const delayMs = Math.min(nextIntervalMs, remainingMs);
+        try {
+            await waitForNextPoll(delayMs, options.signal);
+        }
+        catch (error) {
+            return {
+                success: false,
+                requestId,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+                kind: 'aborted',
+                reason: formatAbortReason(error),
+                ...(lastResult ? { lastResult } : {}),
+            };
+        }
+        nextIntervalMs = Math.min(maxIntervalMs, Math.round(nextIntervalMs * backoffMultiplier));
+    }
+}
+export async function claimSecretRequest(gateway, sessionId, requestId, claimId, options = {}) {
+    try {
+        const response = await claimRemoteSecret(gateway, sessionId, requestId, claimId, options);
+        return {
+            success: true,
+            result: mapClaimedRemoteSecret(response),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            kind: isMagicPayAbortError(error) ? 'aborted' : classifySecretClaimFailure(error),
+            reason: isMagicPayAbortError(error) ? formatAbortReason(error) : formatUnknownSdkError(error),
+            ...(error instanceof MagicPayRequestError ? { status: error.status } : {}),
+            ...(error instanceof MagicPayRequestError ? { errorCode: error.errorCode } : {}),
+        };
+    }
+}
+export function classifySecretClaimFailure(error) {
+    if (isMagicPayAbortError(error)) {
+        return 'aborted';
+    }
+    const errorCode = getMagicPayErrorCode(error);
+    if (errorCode &&
+        SECRET_REQUEST_NOT_FULFILLED_CODES.includes(errorCode)) {
+        return 'not_fulfilled';
+    }
+    if (errorCode &&
+        SECRET_REQUEST_ALREADY_CLAIMED_CODES.includes(errorCode)) {
+        return 'already_claimed';
+    }
+    return 'other';
+}