@railbeam/stardorm-api-contract 0.0.1

package/src/kyc.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+/** Stripe Identity–backed lifecycle for a wallet user. */
+export const userKycStatusSchema = z.enum([
+  "not_started",
+  "pending",
+  "processing",
+  "verified",
+  "requires_input",
+  "canceled",
+]);
+
+export type UserKycStatus = z.infer<typeof userKycStatusSchema>;
+
+export const stripeKycInputSchema = z
+  .object({
+    /** App path + query (e.g. `/` or `/?conversation=<id>`); joined with `APP_PUBLIC_URL` for Stripe `return_url`. */
+    returnPath: z.string().min(1).max(512).optional(),
+  })
+  .strict();
+
+export type StripeKycInput = z.infer<typeof stripeKycInputSchema>;
+
+export const userKycStatusDocumentSchema = z.object({
+  walletAddress: z.string().min(1),
+  status: userKycStatusSchema,
+  stripeVerificationSessionId: z.string().optional(),
+  lastStripeEventType: z.string().optional(),
+  lastError: z.string().optional(),
+  createdAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+});
+
+export type UserKycStatusDocument = z.infer<typeof userKycStatusDocumentSchema>;

package/src/on-ramp.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { x402SupportedAssetSchema } from "./chat-api.js";
+
+export const onRampFormNetworkOptionSchema = z.object({
+  id: z.string().min(1).max(64),
+  label: z.string().min(1).max(120),
+});
+
+/** Persisted on the chat CTA row until the user submits the on-ramp form. */
+export const onRampFormCtaParamsSchema = z.object({
+  _onRampForm: z.literal(true),
+  supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+  networks: z.array(onRampFormNetworkOptionSchema).max(16).optional(),
+  intro: z.string().max(2000).optional(),
+});
+
+export type OnRampFormCtaParams = z.infer<typeof onRampFormCtaParamsSchema>;
+
+export function isOnRampFormCtaParams(v: unknown): v is OnRampFormCtaParams {
+  return onRampFormCtaParamsSchema.safeParse(v).success;
+}
+
+const weiString = z.union([
+  z
+    .string()
+    .trim()
+    .regex(
+      /^[1-9]\d*$/,
+      "tokenAmountWei must be base units (positive integer string, no decimals)",
+    ),
+  z.number().int().positive().transform((n) => String(n)),
+]);
+
+const evmAddr = z
+  .string()
+  .min(1)
+  .refine(
+    (s) => /^0x[a-fA-F0-9]{40}$/.test(s.trim()),
+    "must be a 0x-prefixed 20-byte address",
+  )
+  .transform((s) => s.trim().toLowerCase());
+
+/** Execution payload for `on_ramp_tokens` (Stripe Checkout + treasury ERC-20 send). */
+export const onRampTokensInputSchema = z.object({
+  recipientWallet: evmAddr,
+  network: z.string().min(1).max(64),
+  tokenAddress: evmAddr,
+  tokenDecimals: z.number().int().min(0).max(36),
+  tokenSymbol: z.string().min(1).max(32),
+  tokenAmountWei: weiString,
+  /** Optional spot reference for analytics / UI (per supported token). */
+  usdValue: z.number().finite().nonnegative().optional(),
+  /** Total USD charged via Stripe (cents). Minimum $1.00. */
+  usdAmountCents: z.number().int().min(100).max(10_000_000),
+});
+
+export type OnRampTokensInput = z.infer<typeof onRampTokensInputSchema>;
+
+export const onRampRecordStatusSchema = z.enum([
+  "pending_checkout",
+  "pending_payment",
+  "paid_pending_transfer",
+  "fulfilled",
+  "failed",
+  "canceled",
+]);
+
+export type OnRampRecordStatus = z.infer<typeof onRampRecordStatusSchema>;
+
+export const onRampRecordSchema = z.object({
+  id: z.string().min(1),
+  status: onRampRecordStatusSchema,
+  walletAddress: z.string().min(1),
+  recipientWallet: z.string().min(1),
+  network: z.string().min(1),
+  tokenAddress: z.string().min(1),
+  tokenDecimals: z.number().int().min(0).max(36),
+  tokenSymbol: z.string().min(1),
+  tokenAmountWei: z.string().min(1),
+  usdAmountCents: z.number().int().nonnegative(),
+  usdValue: z.number().finite().nonnegative().optional(),
+  stripeCheckoutSessionId: z.string().optional(),
+  stripePaymentIntentId: z.string().optional(),
+  fulfillmentTxHash: z.string().optional(),
+  errorMessage: z.string().optional(),
+  createdAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+});
+
+export type OnRampRecord = z.infer<typeof onRampRecordSchema>;
+
+/** Query for GET `/users/me/on-ramps`. */
+export const meOnRampsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(50).default(20),
+});
+
+export type MeOnRampsQuery = z.infer<typeof meOnRampsQuerySchema>;
+
+export const onRampsListResponseSchema = z.object({
+  items: z.array(onRampRecordSchema),
+});
+
+export type OnRampsListResponse = z.infer<typeof onRampsListResponseSchema>;

package/src/payment-request.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { stardormChatAttachmentSchema } from "./chat-api.js";
+
+const evmTxHashSchema = z
+  .string()
+  .regex(/^0x[a-fA-F0-9]{64}$/i, "Invalid transaction hash");
+
+const evmAddressSchema = z
+  .string()
+  .regex(/^0x[a-fA-F0-9]{40}$/i, "Invalid address");
+
+/**
+ * Body for POST `/payments/:id/pay`.
+ * Either record a broadcast EVM tx (`txHash`), or submit a full x402 `PaymentPayload` for facilitator verify+settle when `X402_FACILITATOR_URL` is configured.
+ */
+export const paymentSettlementBodySchema = z
+  .object({
+    txHash: evmTxHashSchema.optional(),
+    payerAddress: evmAddressSchema.optional(),
+    /** Matches @x402/core `PaymentPayload` (x402Version, accepted, payload, …). */
+    x402PaymentPayload: z.record(z.string(), z.unknown()).optional(),
+  })
+  .superRefine((val, ctx) => {
+    if (!val.txHash && !val.x402PaymentPayload) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Provide txHash (direct settlement) or x402PaymentPayload (facilitator).",
+        path: ["txHash"],
+      });
+    }
+    if (val.txHash && val.x402PaymentPayload) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Provide only one of txHash or x402PaymentPayload.",
+        path: ["txHash"],
+      });
+    }
+  });
+
+export type PaymentSettlementBody = z.infer<typeof paymentSettlementBodySchema>;
+
+export const paymentRequestTypeSchema = z.enum(["on-chain", "x402"]);
+
+export const paymentRequestStatusSchema = z.enum([
+  "pending",
+  "paid",
+  "expired",
+  "cancelled",
+]);
+
+export const publicPaymentRequestSchema = z.object({
+  id: z.string(),
+  type: paymentRequestTypeSchema,
+  status: paymentRequestStatusSchema,
+  title: z.string(),
+  description: z.string().optional(),
+  asset: z.string(),
+  amount: z.string(),
+  payTo: z.string(),
+  network: z.string(),
+  expiresAt: z.string().optional(),
+  resourceId: z.string().optional(),
+  resourceUrl: z.string().max(2048).optional(),
+  decimals: z.number().int().min(0).max(36).optional(),
+  x402Payload: z.record(z.string(), z.unknown()).optional(),
+  attachment: stardormChatAttachmentSchema.optional(),
+  /** Set when status is `paid` (on-chain settlement recorded). */
+  txHash: z.string().optional(),
+  paidByWallet: z.string().optional(),
+});
+
+export type PublicPaymentRequest = z.infer<typeof publicPaymentRequestSchema>;
+
+/** Query for GET `/users/me/payment-requests`. */
+export const mePaymentRequestsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(50).default(20),
+});
+
+export type MePaymentRequestsQuery = z.infer<typeof mePaymentRequestsQuerySchema>;
+
+export const paymentRequestsListResponseSchema = z.object({
+  items: z.array(publicPaymentRequestSchema),
+});
+
+export type PaymentRequestsListResponse = z.infer<
+  typeof paymentRequestsListResponseSchema
+>;

package/src/storage.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const storageUploadBodySchema = z.object({
+  content: z.string().min(1),
+});
+
+export const storageUploadResponseSchema = z.object({
+  rootHash: z.string().min(1),
+  txHash: z.string().optional(),
+});
+
+export type StorageUploadBody = z.infer<typeof storageUploadBodySchema>;
+export type StorageUploadResponse = z.infer<typeof storageUploadResponseSchema>;

package/src/tax-rate-for-country.ts

@@ -0,0 +1,50 @@
+/** EU-27 member states (post-Brexit, excluding GB). */
+const EU27 = new Set([
+  "AT",
+  "BE",
+  "BG",
+  "HR",
+  "CY",
+  "CZ",
+  "DK",
+  "EE",
+  "FI",
+  "FR",
+  "DE",
+  "GR",
+  "HU",
+  "IE",
+  "IT",
+  "LV",
+  "LT",
+  "LU",
+  "MT",
+  "NL",
+  "PL",
+  "PT",
+  "RO",
+  "SK",
+  "SI",
+  "ES",
+  "SE",
+]);
+
+const EEA_NON_EU = new Set(["IS", "LI", "NO"]);
+
+const HIGH_TIER_OECD = new Set(["AU", "CA", "JP", "KR", "NZ"]);
+
+/**
+ * Approximate headline rate for PDF math when native activity is priced in USD.
+ * Not tax advice; every jurisdiction has nuance. Unknown ISO codes use the same default as the historical stub (0.2).
+ */
+export function taxRateForCountry(country: string): number {
+  const c = country.toUpperCase();
+  if (c === "US") return 0.22;
+  if (c === "GB" || c === "UK") return 0.2;
+  if (c === "DE" || c === "FR") return 0.25;
+  if (c === "SG") return 0.17;
+  if (EU27.has(c)) return 0.24;
+  if (EEA_NON_EU.has(c)) return 0.24;
+  if (HIGH_TIER_OECD.has(c)) return 0.25;
+  return 0.2;
+}

package/src/transfer-drafts.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+
+const caip2Eip155 = z
+  .string()
+  .min(8)
+  .max(64)
+  .regex(
+    /^eip155:\d+$/,
+    "network must be CAIP-2 form eip155:<chainId> (e.g. eip155:16602)",
+  );
+
+const evmAddress20 = z
+  .string()
+  .trim()
+  .refine(
+    (s) => /^0x[a-fA-F0-9]{40}$/.test(s),
+    "must be a 0x-prefixed 20-byte EVM address",
+  )
+  .transform((s) => s.trim().toLowerCase());
+
+/** Positive integer string in base units (no decimals, no leading zeros except single "0" disallowed for valueWei — use /^[1-9]\\d*$/ for strictly positive). */
+const positiveWeiString = z
+  .string()
+  .trim()
+  .regex(
+    /^[1-9]\d*$/,
+    "must be a positive integer decimal string (base units / wei)",
+  );
+
+const decimalStringNonNeg = z
+  .string()
+  .trim()
+  .regex(/^\d+$/, "must be a non-negative integer decimal string");
+
+const nftStandardSchema = z.enum(["erc721", "erc1155"]);
+
+export const draftNativeTransferInputSchema = z.object({
+  network: caip2Eip155,
+  to: evmAddress20,
+  valueWei: positiveWeiString,
+  note: z.string().max(500).optional(),
+});
+
+export type DraftNativeTransferInput = z.infer<
+  typeof draftNativeTransferInputSchema
+>;
+
+export const draftErc20TransferInputSchema = z.object({
+  network: caip2Eip155,
+  token: evmAddress20,
+  tokenSymbol: z.string().min(1).max(32).optional(),
+  tokenDecimals: z.number().int().min(0).max(36),
+  to: evmAddress20,
+  amountWei: positiveWeiString,
+  note: z.string().max(500).optional(),
+});
+
+export type DraftErc20TransferInput = z.infer<
+  typeof draftErc20TransferInputSchema
+>;
+
+export const draftNftTransferInputSchema = z
+  .object({
+    network: caip2Eip155,
+    contract: evmAddress20,
+    standard: nftStandardSchema.default("erc721"),
+    to: evmAddress20,
+    tokenId: decimalStringNonNeg,
+    /** Required for ERC-1155; omit for ERC-721. */
+    amount: positiveWeiString.optional(),
+    note: z.string().max(500).optional(),
+  })
+  .superRefine((val, ctx) => {
+    if (val.standard === "erc1155") {
+      if (!val.amount) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "amount (base units) is required for ERC-1155",
+          path: ["amount"],
+        });
+      }
+    } else if (val.amount != null) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "amount must be omitted for ERC-721",
+        path: ["amount"],
+      });
+    }
+  });
+
+export type DraftNftTransferInput = z.infer<typeof draftNftTransferInputSchema>;

package/src/user.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { handlerActionIdSchema } from "./handlers.js";
+import { stardormChatRichBlockSchema } from "./chat-api.js";
+
+export const userAvatarPresetSchema = z.enum(["male", "female"]);
+
+export const userPreferencesSchema = z.object({
+  autoRoutePrompts: z.boolean(),
+  onchainReceipts: z.boolean(),
+  emailNotifications: z.boolean(),
+  avatarPreset: userAvatarPresetSchema.default("male"),
+});
+
+export const publicUserSchema = z.object({
+  id: z.string().min(1),
+  walletAddress: z.string().min(1),
+  displayName: z.string().optional(),
+  email: z.string().optional(),
+  activeAgentId: z.string().min(1),
+  /** Selected chat thread id when multi-conversation is enabled. */
+  activeConversationId: z.string().min(1).optional(),
+  preferences: userPreferencesSchema,
+  lastLoginAt: z.coerce.date().optional(),
+  createdAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+});
+
+export const updateUserBodySchema = z.object({
+  displayName: z.string().optional(),
+  email: z.string().nullable().optional(),
+  activeAgentId: z.string().optional(),
+  activeConversationId: z.string().nullable().optional(),
+  preferences: userPreferencesSchema.partial().optional(),
+});
+
+export const userUploadResultSchema = z.object({
+  rootHash: z.string().min(1),
+  txHash: z.string().optional(),
+  originalName: z.string(),
+  mimeType: z.string(),
+  size: z.number().int().nonnegative(),
+});
+
+export const executeHandlerBodySchema = z.object({
+  handler: handlerActionIdSchema,
+  params: z.unknown().optional(),
+  /** Mongo id of the chat message that displayed the handler CTA (required). */
+  ctaMessageId: z.string().min(1),
+});
+
+const handlerAttachmentSchema = z.object({
+  rootHash: z.string(),
+  mimeType: z.string(),
+  name: z.string(),
+});
+
+export const executeHandlerResponseSchema = z.object({
+  message: z.string(),
+  attachments: z.array(handlerAttachmentSchema).optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+  rich: stardormChatRichBlockSchema.optional(),
+});
+
+export type UserAvatarPreset = z.infer<typeof userAvatarPresetSchema>;
+
+export type PublicUser = z.infer<typeof publicUserSchema>;
+export type UpdateUserBody = z.infer<typeof updateUserBodySchema>;
+export type UserUploadResult = z.infer<typeof userUploadResultSchema>;
+export type ExecuteHandlerBody = z.infer<typeof executeHandlerBodySchema>;
+export type ExecuteHandlerResponse = z.infer<typeof executeHandlerResponseSchema>;

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  treeshake: true,
+});