@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/core/session/settingsSession.js

@@ -0,0 +1 @@
+export {};

package/dist/core/session/settingsSessions.js

@@ -0,0 +1,43 @@
+import { cloneLocalSession, createLocalSessionBase, isLocalSessionExpired, tokenMatchesHash } from "./localSession.js";
+export class SettingsSessionManager {
+    options;
+    sessions = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async create(now) {
+        const { base, token } = createLocalSessionBase(now, this.options.ttlMs);
+        const session = {
+            ...base,
+            type: "local_settings"
+        };
+        this.sessions.set(session.id, session);
+        await this.options.appendEventLog({
+            type: "settings_session.created",
+            sessionId: session.id,
+            at: now.toISOString()
+        });
+        return { session: cloneLocalSession(session), token };
+    }
+    async get(id, now) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return undefined;
+        }
+        if (isLocalSessionExpired(session, now)) {
+            this.sessions.delete(id);
+            return undefined;
+        }
+        return cloneLocalSession(session);
+    }
+    async validateToken(id, token, now) {
+        const session = await this.get(id, now);
+        if (!session) {
+            return false;
+        }
+        return tokenMatchesHash(session.tokenHash, token);
+    }
+    clear() {
+        this.sessions.clear();
+    }
+}

package/dist/core/session/status.js

@@ -0,0 +1,86 @@
+export const EXECUTION_POLLING_INTERVAL_SECONDS = 3;
+export const EXECUTION_STATUS_CATEGORIES = [
+    "final",
+    "user_action_required",
+    "awaiting_chain_result",
+    "non_terminal"
+];
+export function isFinalSessionStatus(status) {
+    return status === "success" || status === "failure" || status === "expired";
+}
+export function executionPollingHint() {
+    return {
+        nonTerminalStatuses: [
+            "pending",
+            "awaiting_wallet",
+            "awaiting_signature",
+            "signed_pending_result"
+        ],
+        waitStoppingStatuses: ["success", "failure", "refresh_required", "blocked", "expired"],
+        finalStatuses: ["success", "failure", "expired"],
+        userActionRequiredStatuses: ["refresh_required", "blocked"],
+        recommendedIntervalSeconds: EXECUTION_POLLING_INTERVAL_SECONDS
+    };
+}
+export function executionStatusCategory(status) {
+    switch (status) {
+        case "success":
+        case "failure":
+        case "expired":
+            return "final";
+        case "blocked":
+        case "refresh_required":
+            return "user_action_required";
+        case "signed_pending_result":
+            return "awaiting_chain_result";
+        case "pending":
+        case "awaiting_wallet":
+        case "awaiting_signature":
+            return "non_terminal";
+        default:
+            return assertNever(status);
+    }
+}
+export function isWaitStoppingExecutionStatus(status) {
+    const category = executionStatusCategory(status);
+    return category === "final" || category === "user_action_required";
+}
+export function isInteractionPendingReviewStatus(status) {
+    const category = executionStatusCategory(status);
+    return category !== "final";
+}
+export function getExecutionPollingStatus(session) {
+    if (session.status === "expired") {
+        return "expired";
+    }
+    if (session.executionResult) {
+        return executionResultStatus(session.executionResult);
+    }
+    switch (session.status) {
+        case "proposed":
+            return "pending";
+        case "awaiting_wallet":
+            return "awaiting_wallet";
+        case "wallet_connected":
+        case "ready_for_wallet_review":
+            return "awaiting_signature";
+        case "refresh_required":
+            return "refresh_required";
+        case "blocked":
+            return "blocked";
+        case "signed_pending_result":
+            return "signed_pending_result";
+        case "success":
+            return "success";
+        case "failure":
+            return "failure";
+        default:
+            return assertNever(session.status);
+    }
+}
+function executionResultStatus(result) {
+    return result.status;
+}
+function assertNever(value) {
+    throw new Error(`Unhandled session status: ${String(value)}`);
+}

package/dist/core/session/transactionMaterialStore.js

@@ -0,0 +1,205 @@
+import { randomUUID } from "node:crypto";
+import { Transaction } from "@mysten/sui/transactions";
+import { z } from "zod";
+import { normalizedSuiAddressSchema, parseSuiAddress, suiTransactionDigestSchema } from "../suiAddress.js";
+export const LOCAL_TRANSACTION_MATERIAL_KINDS = [
+    "deepbook_swap_transaction_data",
+    "flowx_swap_transaction_data"
+];
+export const LOCAL_TRANSACTION_MATERIAL_SOURCES = [
+    "say_ur_intent_built",
+    "say_ur_intent_verified"
+];
+const localTransactionMaterialKindSchema = z.enum(LOCAL_TRANSACTION_MATERIAL_KINDS);
+const localTransactionMaterialSourceSchema = z.enum(LOCAL_TRANSACTION_MATERIAL_SOURCES);
+const isoUtcStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+export const localTransactionMaterialHandleSchema = z.object({
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    kind: localTransactionMaterialKindSchema,
+    source: localTransactionMaterialSourceSchema,
+    createdAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+}).superRefine((value, ctx) => {
+    if (Date.parse(value.expiresAt) <= Date.parse(value.createdAt)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "expiresAt must be after createdAt"
+        });
+    }
+});
+export const localTransactionMaterialDigestCommitmentSchema = z.object({
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    kind: localTransactionMaterialKindSchema,
+    source: localTransactionMaterialSourceSchema,
+    digestKind: z.literal("sui_transaction_digest"),
+    transactionDigest: suiTransactionDigestSchema,
+    computedAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+});
+export function parseLocalTransactionMaterialHandle(value) {
+    return localTransactionMaterialHandleSchema.parse(value);
+}
+export function parseLocalTransactionMaterialDigestCommitment(value) {
+    return localTransactionMaterialDigestCommitmentSchema.parse(value);
+}
+function parseLocalTransactionMaterialArtifacts(value, now = new Date()) {
+    const transactionMaterial = parseLocalTransactionMaterialHandle(value.transactionMaterial);
+    const transactionMaterialDigest = parseLocalTransactionMaterialDigestCommitment(value.transactionMaterialDigest);
+    const materialCreatedAtMs = Date.parse(transactionMaterial.createdAt);
+    const materialExpiresAtMs = Date.parse(transactionMaterial.expiresAt);
+    const digestComputedAtMs = Date.parse(transactionMaterialDigest.computedAt);
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        throw new LocalTransactionMaterialStoreError("now must be a valid Date");
+    }
+    if (materialCreatedAtMs > nowMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material createdAt must not be in the future");
+    }
+    if (materialExpiresAtMs <= nowMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material must not be expired");
+    }
+    if (digestComputedAtMs < materialCreatedAtMs || digestComputedAtMs > nowMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest computedAt must be between createdAt and now");
+    }
+    if (digestComputedAtMs >= materialExpiresAtMs) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest must be computed before material expiry");
+    }
+    if (transactionMaterialDigest.materialId !== transactionMaterial.materialId ||
+        transactionMaterialDigest.reviewSessionId !== transactionMaterial.reviewSessionId ||
+        transactionMaterialDigest.planId !== transactionMaterial.planId ||
+        transactionMaterialDigest.account !== transactionMaterial.account ||
+        transactionMaterialDigest.kind !== transactionMaterial.kind ||
+        transactionMaterialDigest.source !== transactionMaterial.source ||
+        transactionMaterialDigest.expiresAt !== transactionMaterial.expiresAt) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest must match the material handle");
+    }
+    return { transactionMaterial, transactionMaterialDigest };
+}
+export async function verifyLocalTransactionMaterialArtifacts(value) {
+    const now = value.now ?? new Date();
+    const parsed = parseLocalTransactionMaterialArtifacts({
+        transactionMaterial: value.transactionMaterial,
+        transactionMaterialDigest: value.transactionMaterialDigest
+    }, now);
+    const material = value.materialStore.getTransactionMaterial(parsed.transactionMaterial, now);
+    if (!material) {
+        throw new LocalTransactionMaterialStoreError("transaction material is unavailable");
+    }
+    let transactionDigest;
+    try {
+        transactionDigest = await Transaction.from(material.transactionBytes).getDigest();
+    }
+    catch {
+        throw new LocalTransactionMaterialStoreError("transaction material bytes cannot produce a Sui transaction digest");
+    }
+    const parsedDigest = suiTransactionDigestSchema.safeParse(transactionDigest);
+    if (!parsedDigest.success) {
+        throw new LocalTransactionMaterialStoreError("computed transaction digest is invalid");
+    }
+    if (parsedDigest.data !== parsed.transactionMaterialDigest.transactionDigest) {
+        throw new LocalTransactionMaterialStoreError("transaction material digest does not match stored transaction bytes");
+    }
+    return parsed;
+}
+export class LocalTransactionMaterialStoreError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+export class InMemoryLocalTransactionMaterialStore {
+    records = new Map();
+    recordTransactionMaterial(input, now = new Date()) {
+        const account = parseSuiAddress(input.account);
+        if (!account) {
+            throw new LocalTransactionMaterialStoreError("Invalid transaction material account");
+        }
+        if (!input.reviewSessionId) {
+            throw new LocalTransactionMaterialStoreError("reviewSessionId is required");
+        }
+        if (!input.planId) {
+            throw new LocalTransactionMaterialStoreError("planId is required");
+        }
+        if (!LOCAL_TRANSACTION_MATERIAL_KINDS.includes(input.kind)) {
+            throw new LocalTransactionMaterialStoreError("Invalid transaction material kind");
+        }
+        if (!LOCAL_TRANSACTION_MATERIAL_SOURCES.includes(input.source)) {
+            throw new LocalTransactionMaterialStoreError("Invalid transaction material source");
+        }
+        if (input.transactionBytes.byteLength === 0) {
+            throw new LocalTransactionMaterialStoreError("transactionBytes must not be empty");
+        }
+        const createdAt = now.toISOString();
+        const expiresAt = input.expiresAt.toISOString();
+        if (Date.parse(expiresAt) <= Date.parse(createdAt)) {
+            throw new LocalTransactionMaterialStoreError("expiresAt must be after createdAt");
+        }
+        const handle = {
+            materialId: `txmat_${randomUUID()}`,
+            reviewSessionId: input.reviewSessionId,
+            planId: input.planId,
+            account,
+            kind: input.kind,
+            source: input.source,
+            createdAt,
+            expiresAt
+        };
+        this.records.set(handle.materialId, {
+            ...handle,
+            transactionBytes: cloneBytes(input.transactionBytes),
+            ...(input.redactedDiagnostics === undefined
+                ? {}
+                : { redactedDiagnostics: structuredClone(input.redactedDiagnostics) })
+        });
+        return { ...handle };
+    }
+    getTransactionMaterial(handle, now = new Date()) {
+        const record = this.records.get(handle.materialId);
+        if (!record) {
+            return undefined;
+        }
+        if (Date.parse(record.expiresAt) <= now.getTime()) {
+            this.records.delete(handle.materialId);
+            return undefined;
+        }
+        if (!sameHandle(record, handle)) {
+            return undefined;
+        }
+        return {
+            ...record,
+            transactionBytes: cloneBytes(record.transactionBytes),
+            ...(record.redactedDiagnostics === undefined
+                ? {}
+                : { redactedDiagnostics: structuredClone(record.redactedDiagnostics) })
+        };
+    }
+    deleteReviewSessionTransactionMaterials(reviewSessionId) {
+        for (const [materialId, record] of this.records) {
+            if (record.reviewSessionId === reviewSessionId) {
+                this.records.delete(materialId);
+            }
+        }
+    }
+}
+function sameHandle(record, handle) {
+    return record.materialId === handle.materialId &&
+        record.reviewSessionId === handle.reviewSessionId &&
+        record.planId === handle.planId &&
+        record.account === handle.account &&
+        record.kind === handle.kind &&
+        record.source === handle.source &&
+        record.createdAt === handle.createdAt &&
+        record.expiresAt === handle.expiresAt;
+}
+function cloneBytes(bytes) {
+    return new Uint8Array(bytes);
+}

package/dist/core/session/wait.js

@@ -0,0 +1,102 @@
+import { EXECUTION_POLLING_INTERVAL_SECONDS, getExecutionPollingStatus, isWaitStoppingExecutionStatus } from "./status.js";
+import { SessionStoreError } from "./sessionStore.js";
+import { isTerminalWalletIdentityStatus, WALLET_IDENTITY_POLLING_INTERVAL_SECONDS } from "./walletIdentity.js";
+export const DEFAULT_WAIT_TIMEOUT_MS = 45_000;
+export const MAX_WAIT_TIMEOUT_MS = 55_000;
+export class WaitRequestAbortedError extends Error {
+    reason;
+    constructor(reason = "host_abort") {
+        super("Wait request aborted");
+        this.reason = reason;
+    }
+}
+export async function waitForWalletIdentitySession(sessions, walletSessionId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const sleep = options.sleep ?? sleepMs;
+    const startedAt = Date.now();
+    assertNotAborted(options.signal);
+    let session = await getRequiredWalletIdentitySession(sessions, walletSessionId, options.now, "missing");
+    if (isTerminalWalletIdentityStatus(session.status)) {
+        return walletWaitResult("status_reached", session);
+    }
+    while (Date.now() - startedAt < timeoutMs) {
+        assertNotAborted(options.signal);
+        const remainingMs = timeoutMs - (Date.now() - startedAt);
+        await sleep(Math.min(remainingMs, WALLET_IDENTITY_POLLING_INTERVAL_SECONDS * 1000), options.signal);
+        session = await getRequiredWalletIdentitySession(sessions, walletSessionId, options.now, "session_removed_during_wait");
+        if (isTerminalWalletIdentityStatus(session.status)) {
+            return walletWaitResult("status_reached", session);
+        }
+    }
+    return walletWaitResult("timed_out", session);
+}
+export async function waitForExecutionResult(sessions, reviewSessionId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const sleep = options.sleep ?? sleepMs;
+    const startedAt = Date.now();
+    assertNotAborted(options.signal);
+    let session = await getRequiredReviewSession(sessions, reviewSessionId, options.now, "missing");
+    let status = getExecutionPollingStatus(session);
+    if (isWaitStoppingExecutionStatus(status)) {
+        return { waitOutcome: "status_reached", session, status };
+    }
+    while (Date.now() - startedAt < timeoutMs) {
+        assertNotAborted(options.signal);
+        const remainingMs = timeoutMs - (Date.now() - startedAt);
+        await sleep(Math.min(remainingMs, EXECUTION_POLLING_INTERVAL_SECONDS * 1000), options.signal);
+        session = await getRequiredReviewSession(sessions, reviewSessionId, options.now, "session_removed_during_wait");
+        status = getExecutionPollingStatus(session);
+        if (isWaitStoppingExecutionStatus(status)) {
+            return { waitOutcome: "status_reached", session, status };
+        }
+    }
+    return { waitOutcome: "timed_out", session, status };
+}
+export function walletStatusCategory(status) {
+    return isTerminalWalletIdentityStatus(status) ? "terminal" : "non_terminal";
+}
+function walletWaitResult(waitOutcome, session) {
+    return {
+        waitOutcome,
+        session,
+        statusCategory: walletStatusCategory(session.status)
+    };
+}
+async function getRequiredWalletIdentitySession(sessions, walletSessionId, now, reason) {
+    const session = await sessions.getWalletIdentitySession(walletSessionId, now?.());
+    if (!session) {
+        throw new SessionStoreError("session_not_found", `Wallet identity session not found: ${walletSessionId}`, {
+            reason
+        });
+    }
+    return session;
+}
+async function getRequiredReviewSession(sessions, reviewSessionId, now, reason) {
+    const session = await sessions.getReviewSession(reviewSessionId, now?.());
+    if (!session) {
+        throw new SessionStoreError("session_not_found", `Review session not found: ${reviewSessionId}`, { reason });
+    }
+    return session;
+}
+function sleepMs(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new WaitRequestAbortedError());
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new WaitRequestAbortedError());
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted) {
+        throw new WaitRequestAbortedError();
+    }
+}

package/dist/core/session/walletIdentity.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { normalizedSuiAddressSchema } from "../suiAddress.js";
+export const SUI_MAINNET_WALLET_CHAIN = "sui:mainnet";
+export const WALLET_IDENTITY_STATUSES = [
+    "pending",
+    "opened",
+    "connecting",
+    "connected",
+    "rejected",
+    "failed",
+    "expired"
+];
+export const WALLET_IDENTITY_FAILURE_REASONS = [
+    "user_rejected",
+    "no_compatible_wallet",
+    "no_accounts_authorized",
+    "unsupported_chain",
+    "wallet_provider_error"
+];
+const isoDateStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+const walletSessionBaseSchema = {
+    id: z.string(),
+    tokenHash: z.string(),
+    createdAt: isoDateStringSchema,
+    expiresAt: isoDateStringSchema,
+    lastActivityAt: isoDateStringSchema
+};
+const failureDetailSchema = z.string().min(1).max(500).optional();
+export const walletIdentityStatusSchema = z.enum(WALLET_IDENTITY_STATUSES);
+export const walletIdentityFailureReasonSchema = z.enum(WALLET_IDENTITY_FAILURE_REASONS);
+export const nonUserWalletIdentityFailureReasonSchema = z.enum([
+    "no_compatible_wallet",
+    "no_accounts_authorized",
+    "unsupported_chain",
+    "wallet_provider_error"
+]);
+export const walletIdentitySessionSchema = z.discriminatedUnion("status", [
+    z.object({ ...walletSessionBaseSchema, status: z.literal("pending") }),
+    z.object({ ...walletSessionBaseSchema, status: z.literal("opened") }),
+    z.object({ ...walletSessionBaseSchema, status: z.literal("connecting") }),
+    z.object({
+        ...walletSessionBaseSchema,
+        status: z.literal("connected"),
+        account: normalizedSuiAddressSchema,
+        chain: z.literal(SUI_MAINNET_WALLET_CHAIN),
+        walletName: z.string().min(1).optional(),
+        walletId: z.string().min(1).optional()
+    }),
+    z.object({
+        ...walletSessionBaseSchema,
+        status: z.literal("rejected"),
+        failureReason: z.literal("user_rejected"),
+        failureDetail: failureDetailSchema,
+        walletName: z.string().min(1).optional(),
+        walletId: z.string().min(1).optional()
+    }),
+    z.object({
+        ...walletSessionBaseSchema,
+        status: z.literal("failed"),
+        failureReason: nonUserWalletIdentityFailureReasonSchema,
+        failureDetail: failureDetailSchema,
+        walletName: z.string().min(1).optional(),
+        walletId: z.string().min(1).optional()
+    }),
+    z.object({ ...walletSessionBaseSchema, status: z.literal("expired") })
+]);
+export const walletIdentityResultInputSchema = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("connected"),
+        account: normalizedSuiAddressSchema,
+        chain: z.literal(SUI_MAINNET_WALLET_CHAIN),
+        walletName: z.string().min(1).optional(),
+        walletId: z.string().min(1).optional()
+    }),
+    z.object({
+        status: z.literal("rejected"),
+        failureReason: z.literal("user_rejected"),
+        failureDetail: failureDetailSchema,
+        walletName: z.string().min(1).optional(),
+        walletId: z.string().min(1).optional()
+    }),
+    z.object({
+        status: z.literal("failed"),
+        failureReason: nonUserWalletIdentityFailureReasonSchema,
+        failureDetail: failureDetailSchema,
+        walletName: z.string().min(1).optional(),
+        walletId: z.string().min(1).optional()
+    })
+]);
+export function isTerminalWalletIdentityStatus(status) {
+    return status === "connected" || status === "rejected" || status === "failed" || status === "expired";
+}
+export const WALLET_IDENTITY_POLLING_INTERVAL_SECONDS = 5;
+export function walletIdentityPollingHint() {
+    return {
+        nonTerminalStatuses: ["pending", "opened", "connecting"],
+        terminalStatuses: ["connected", "rejected", "failed", "expired"],
+        recommendedIntervalSeconds: WALLET_IDENTITY_POLLING_INTERVAL_SECONDS
+    };
+}