@railbeam/stardorm-api-contract 0.0.1

package/src/chat-api.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { handlerActionIdSchema } from "./handlers.js";
+
+export const stardormChatRichRowSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+
+/** One selectable asset row for the x402 checkout form rich block. */
+export const x402SupportedAssetSchema = z.object({
+  name: z.string().min(1).max(64),
+  symbol: z.string().min(1).max(32),
+  icon: z.string().min(1).max(512),
+  decimals: z.number().int().min(0).max(36),
+  address: z.string().min(1).max(66),
+  usdValue: z.number().finite().nonnegative().optional(),
+});
+
+export type X402SupportedAsset = z.infer<typeof x402SupportedAssetSchema>;
+
+const stardormChatRichRows = z.array(stardormChatRichRowSchema).max(32).optional();
+
+export const stardormChatRichBlockSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("report"),
+    title: z.string().min(1),
+    rows: stardormChatRichRows,
+  }),
+  z.object({
+    type: z.literal("invoice"),
+    title: z.string().min(1),
+    rows: stardormChatRichRows,
+  }),
+  z.object({
+    type: z.literal("tx"),
+    title: z.string().min(1),
+    rows: stardormChatRichRows,
+  }),
+  z.object({
+    type: z.literal("x402_checkout_form"),
+    title: z.string().min(1).max(200),
+    intro: z.string().max(2000).optional(),
+    /** Paywalled HTTP resource URL for x402 clients (optional). */
+    resourceUrl: z.string().url().max(2048).optional(),
+    supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+    networks: z
+      .array(
+        z.object({
+          id: z.string().min(1).max(64),
+          label: z.string().min(1).max(120),
+        }),
+      )
+      .max(16)
+      .optional(),
+  }),
+  z.object({
+    type: z.literal("on_ramp_checkout_form"),
+    title: z.string().min(1).max(200),
+    intro: z.string().max(2000).optional(),
+    supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+    networks: z
+      .array(
+        z.object({
+          id: z.string().min(1).max(64),
+          label: z.string().min(1).max(120),
+        }),
+      )
+      .max(16)
+      .optional(),
+  }),
+  z.object({
+    type: z.literal("credit_card_checkout_form"),
+    title: z.string().min(1).max(200),
+    intro: z.string().max(2000).optional(),
+    /** Pre-filled ISO 4217 currency in the form (e.g. USD). */
+    defaultCurrency: z.string().length(3).optional(),
+  }),
+  z.object({
+    type: z.literal("credit_card"),
+    title: z.string().min(1),
+    rows: stardormChatRichRows,
+  }),
+]);
+
+export type StardormChatRichBlock = z.infer<typeof stardormChatRichBlockSchema>;
+
+export const stardormChatJsonBodySchema = z.object({
+  message: z.string().min(1),
+});
+
+export type StardormChatJsonBody = z.infer<typeof stardormChatJsonBodySchema>;
+
+export const stardormChatStructuredSchema = z.object({
+  text: z.string(),
+  handler: handlerActionIdSchema.optional(),
+  params: z.unknown().optional(),
+});
+
+export const stardormChatComputeSchema = z.object({
+  model: z.string(),
+  verified: z.boolean(),
+  chatId: z.string().optional(),
+  provider: z.string(),
+  computeNetwork: z.string(),
+});
+
+export const stardormChatAttachmentSchema = z.object({
+  id: z.string().min(1),
+  name: z.string(),
+  mimeType: z.string(),
+  hash: z.string().min(1),
+  size: z.string().optional(),
+});
+
+export type StardormChatAttachment = z.infer<typeof stardormChatAttachmentSchema>;
+
+export const stardormChatSuccessSchema = z.object({
+  agentKey: z.string().min(1),
+  reply: z.string(),
+  structured: stardormChatStructuredSchema.optional(),
+  /** Structured card rows for the client (model or server-generated). */
+  rich: stardormChatRichBlockSchema.optional(),
+  /** Files the server uploaded to 0G Storage from the user's chat turn (echoed for immediate render). */
+  attachments: z.array(stardormChatAttachmentSchema).optional(),
+  compute: stardormChatComputeSchema,
+});
+
+export type StardormChatSuccess = z.infer<typeof stardormChatSuccessSchema>;
+
+export const stardormChatClientErrorSchema = z.object({
+  error: z.string().min(1),
+});
+
+export const stardormChatClientResultSchema = z.union([
+  stardormChatSuccessSchema,
+  stardormChatClientErrorSchema,
+]);
+
+export type StardormChatClientResult = z.infer<typeof stardormChatClientResultSchema>;

package/src/conversation.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { handlerActionIdSchema } from "./handlers.js";
+import { stardormChatRichBlockSchema } from "./chat-api.js";
+
+export const chatHistoryQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(40),
+  /** When omitted, the server uses the user’s active conversation. */
+  conversationId: z.string().min(1).optional(),
+  /**
+   * Opaque cursor from the previous response’s `nextCursorOlder` — loads older messages
+   * than the oldest message in the last batch (prepends chronologically in the client).
+   */
+  cursor: z.string().min(1).optional(),
+});
+
+export type ChatHistoryQuery = z.infer<typeof chatHistoryQuerySchema>;
+
+export const chatHistoryAttachmentSchema = z.object({
+  id: z.string(),
+  mimeType: z.string(),
+  name: z.string(),
+  hash: z.string(),
+  size: z.string().optional(),
+});
+
+export const chatHistoryHandlerCtaSchema = z.object({
+  handler: handlerActionIdSchema,
+  params: z.record(z.unknown()),
+});
+
+/** Post-execute affordances derived from handler result (x402 checkout, tax PDF, …). */
+export const chatFollowUpSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("x402_checkout"),
+    /** App-relative path, e.g. `/pay/<mongoId>`. */
+    payPath: z.string().min(1),
+    paymentRequestId: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("tax_report_pdf"),
+    attachmentId: z.string().min(1),
+    name: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("stripe_on_ramp"),
+    checkoutUrl: z.string().url(),
+    onRampId: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("stripe_identity"),
+    verificationUrl: z.string().url(),
+    verificationSessionId: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("credit_card_ready"),
+    creditCardId: z.string().min(1),
+    /** App path for managing the card balance (e.g. /dashboard). */
+    dashboardPath: z.string().min(1),
+  }),
+]);
+
+export const chatHistoryMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["user", "agent"]),
+  agentKey: z.string().optional(),
+  content: z.string(),
+  createdAt: z.number(),
+  attachments: z.array(chatHistoryAttachmentSchema).optional(),
+  rich: stardormChatRichBlockSchema.optional(),
+  handlerCta: chatHistoryHandlerCtaSchema.optional(),
+  followUp: chatFollowUpSchema.optional(),
+  model: z.string().optional(),
+  verified: z.boolean().optional(),
+  chatId: z.string().optional(),
+  provider: z.string().optional(),
+});
+
+export const chatHistoryResponseSchema = z.object({
+  conversationId: z.string(),
+  agentKey: z.string(),
+  messages: z.array(chatHistoryMessageSchema),
+  /** True when more older messages exist before this batch. */
+  hasMoreOlder: z.boolean(),
+  /** Pass as `cursor` on the next request to load older messages. */
+  nextCursorOlder: z.string().optional(),
+});
+
+export type ChatHistoryAttachment = z.infer<typeof chatHistoryAttachmentSchema>;
+export type ChatFollowUp = z.infer<typeof chatFollowUpSchema>;
+export type ChatHistoryMessage = z.infer<typeof chatHistoryMessageSchema>;
+export type ChatHistoryResponse = z.infer<typeof chatHistoryResponseSchema>;
+
+export const conversationSummarySchema = z.object({
+  id: z.string().min(1),
+  agentKey: z.string().min(1),
+  title: z.string().optional(),
+  lastMessageAt: z.coerce.date(),
+  createdAt: z.coerce.date().optional(),
+});
+
+export const conversationsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(50).default(25),
+  /** Opaque cursor from the previous response’s `nextCursor`. */
+  cursor: z.string().min(1).optional(),
+});
+
+export type ConversationsQuery = z.infer<typeof conversationsQuerySchema>;
+
+export const conversationsPageResponseSchema = z.object({
+  conversations: z.array(conversationSummarySchema),
+  hasMore: z.boolean(),
+  nextCursor: z.string().optional(),
+});
+
+/** @deprecated Use `conversationsPageResponseSchema` — same shape. */
+export const conversationsListResponseSchema = conversationsPageResponseSchema;
+
+export const createConversationBodySchema = z.object({
+  title: z.string().max(120).optional(),
+  agentKey: z.string().min(1).optional(),
+});
+
+export type ConversationSummary = z.infer<typeof conversationSummarySchema>;
+export type ConversationsPageResponse = z.infer<typeof conversationsPageResponseSchema>;
+export type ConversationsListResponse = ConversationsPageResponse;
+export type CreateConversationBody = z.infer<typeof createConversationBodySchema>;
+
+export const deleteConversationResponseSchema = z.object({
+  deleted: z.literal(true),
+});
+
+export type DeleteConversationResponse = z.infer<typeof deleteConversationResponseSchema>;

package/src/credit-card.ts

@@ -0,0 +1,150 @@
+import { z } from "zod";
+
+export const createCreditCardInputSchema = z.object({
+  firstName: z.string().trim().min(1).max(80),
+  lastName: z.string().trim().min(1).max(80),
+  line1: z.string().trim().min(1).max(120),
+  line2: z.string().trim().max(120).optional(),
+  city: z.string().trim().min(1).max(80),
+  region: z.string().trim().min(1).max(80),
+  postalCode: z.string().trim().min(1).max(20),
+  countryCode: z
+    .string()
+    .trim()
+    .length(2)
+    .transform((c) => c.toUpperCase()),
+  cardLabel: z.string().trim().min(1).max(80).optional(),
+  currency: z
+    .string()
+    .trim()
+    .length(3)
+    .transform((c) => c.toUpperCase())
+    .optional(),
+  /** Opening balance in minor units (e.g. USD cents). */
+  initialBalanceCents: z.coerce.number().int().min(0).max(100_000_000).optional(),
+});
+
+export type CreateCreditCardInput = z.infer<typeof createCreditCardInputSchema>;
+
+/** Persisted on the chat CTA row until the user submits the virtual-card billing form. */
+export const creditCardFormCtaParamsSchema = z.object({
+  _creditCardForm: z.literal(true),
+  intro: z.string().max(2000).optional(),
+  defaultCurrency: z
+    .string()
+    .trim()
+    .length(3)
+    .transform((c) => c.toUpperCase())
+    .optional(),
+});
+
+export type CreditCardFormCtaParams = z.infer<typeof creditCardFormCtaParamsSchema>;
+
+export function isCreditCardFormCtaParams(v: unknown): v is CreditCardFormCtaParams {
+  return creditCardFormCtaParamsSchema.safeParse(v).success;
+}
+
+export const creditCardPublicSchema = z.object({
+  id: z.string().min(1),
+  firstName: z.string(),
+  lastName: z.string(),
+  cardLabel: z.string().optional(),
+  line1: z.string(),
+  line2: z.string().optional(),
+  city: z.string(),
+  region: z.string(),
+  postalCode: z.string(),
+  countryCode: z.string(),
+  currency: z.string(),
+  balanceCents: z.number().int().nonnegative(),
+  last4: z.string(),
+  networkBrand: z.string(),
+  status: z.enum(["active", "frozen"]),
+  createdAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+  /** Present on some `POST …/withdraw` responses when native 0G was sent from the treasury. */
+  lastWithdrawTxHash: z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{64}$/)
+    .optional(),
+});
+
+export type CreditCardPublic = z.infer<typeof creditCardPublicSchema>;
+
+/** Wallet-authenticated only; never included in list cards responses. */
+export const creditCardSensitiveDetailsSchema = z.object({
+  cardId: z.string().min(1),
+  pan: z.string().regex(/^\d{16}$/),
+  expiryMonth: z.coerce.number().int().min(1).max(12),
+  expiryYear: z.coerce.number().int().min(2000).max(2100),
+  cvv: z.string().regex(/^\d{3,4}$/),
+});
+
+export type CreditCardSensitiveDetails = z.infer<
+  typeof creditCardSensitiveDetailsSchema
+>;
+
+export const creditCardsListResponseSchema = z.object({
+  cards: z.array(creditCardPublicSchema),
+});
+
+export type CreditCardsListResponse = z.infer<typeof creditCardsListResponseSchema>;
+
+export const creditCardFundBodySchema = z
+  .object({
+    amountCents: z.coerce.number().int().min(1).max(100_000_000),
+    fundingTxHash: z
+      .string()
+      .regex(/^0x[a-fA-F0-9]{64}$/)
+      .optional(),
+    fundingChainId: z.coerce.number().int().positive().optional(),
+  })
+  .refine(
+    (d) =>
+      (d.fundingTxHash == null && d.fundingChainId == null) ||
+      (d.fundingTxHash != null && d.fundingChainId != null),
+    {
+      message:
+        "fundingTxHash and fundingChainId must both be provided or both omitted",
+      path: ["fundingTxHash"],
+    },
+  );
+
+export type CreditCardFundBody = z.infer<typeof creditCardFundBodySchema>;
+
+export const creditCardFundQuoteQuerySchema = z.object({
+  amountCents: z.coerce.number().int().min(1).max(100_000_000),
+});
+
+export type CreditCardFundQuoteQuery = z.infer<
+  typeof creditCardFundQuoteQuerySchema
+>;
+
+export const creditCardFundQuoteOffChainSchema = z.object({
+  onchainFundingRequired: z.literal(false),
+});
+
+export const creditCardFundQuoteOnChainSchema = z.object({
+  onchainFundingRequired: z.literal(true),
+  chainId: z.number().int(),
+  recipient: z.string().min(1),
+  minNativeWei: z.string().regex(/^\d+$/),
+  usdValue: z.number().finite().positive(),
+  nativeSymbol: z.string().min(1),
+  nativeDecimals: z.number().int().min(0).max(18),
+});
+
+export const creditCardFundQuoteResponseSchema = z.discriminatedUnion(
+  "onchainFundingRequired",
+  [creditCardFundQuoteOffChainSchema, creditCardFundQuoteOnChainSchema],
+);
+
+export type CreditCardFundQuoteResponse = z.infer<
+  typeof creditCardFundQuoteResponseSchema
+>;
+
+export const creditCardWithdrawBodySchema = z.object({
+  amountCents: z.coerce.number().int().min(1).max(100_000_000),
+});
+
+export type CreditCardWithdrawBody = z.infer<typeof creditCardWithdrawBodySchema>;

package/src/handlers.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+/**
+ * Source of truth for backend handler ids implemented in
+ * `stardorm/backend/src/handlers/handlers.service.ts`. Keep in sync.
+ */
+export const HANDLER_ACTION_IDS = [
+  "generate_tax_report",
+  "create_x402_payment",
+  /** Fiat checkout via Stripe; webhook fulfills ERC-20 transfer from treasury key. */
+  "on_ramp_tokens",
+  /** Stripe Identity hosted verification for the signed-in wallet user. */
+  "complete_stripe_kyc",
+  /** Issue a virtual payment card record with billing profile and spend balance. */
+  "create_credit_card",
+  /** PDF + structured snapshot: payment requests, on-ramps, cards, KYC for this wallet. */
+  "generate_payment_invoice",
+  /** Summary report across payment requests, on-ramps, virtual cards, and KYC status. */
+  "generate_financial_activity_report",
+  /** Confirms a native (gas token) transfer draft; user signs in their wallet / Beam Send. */
+  "draft_native_transfer",
+  /** Confirms an ERC-20 transfer draft; user signs in their wallet / Beam Send. */
+  "draft_erc20_transfer",
+  /** Confirms an NFT (ERC-721 / ERC-1155) transfer draft; user signs in their wallet / Beam Send. */
+  "draft_nft_transfer",
+] as const;
+
+export type HandlerActionId = (typeof HANDLER_ACTION_IDS)[number];
+
+export function isHandlerActionId(id: string): id is HandlerActionId {
+  return (HANDLER_ACTION_IDS as readonly string[]).includes(id);
+}
+
+export const handlerActionIdSchema = z.enum(HANDLER_ACTION_IDS);
+
+export const handlersListResponseSchema = z.object({
+  handlers: z.array(handlerActionIdSchema),
+});
+
+export type HandlersListResponse = z.infer<typeof handlersListResponseSchema>;

package/src/index.ts

@@ -0,0 +1,192 @@
+export {
+  agentAvatarSchema,
+  agentCategorySchema,
+  agentSchema,
+  agentsListSchema,
+  skillHandleSchema,
+  type Agent,
+  type AgentCategory,
+  type SkillHandle,
+} from "./agent.js";
+export { catalogResponseSchema, type CatalogResponse } from "./catalog.js";
+export { buildStardormCatalogResponse } from "./catalog-marketplace-response.js";
+export {
+  resolveStardormAgentKey,
+  resolveStardormChainAgentId,
+} from "./catalog-build.js";
+export {
+  authChallengeBodySchema,
+  authChallengeResponseSchema,
+  authVerifyBodySchema,
+  authVerifyResponseSchema,
+  authMeResponseSchema,
+  type AuthChallengeBody,
+  type AuthChallengeResponse,
+  type AuthVerifyBody,
+  type AuthVerifyResponse,
+  type AuthMeResponse,
+} from "./auth.js";
+export {
+  HANDLER_ACTION_IDS,
+  handlerActionIdSchema,
+  handlersListResponseSchema,
+  isHandlerActionId,
+  type HandlerActionId,
+  type HandlersListResponse,
+} from "./handlers.js";
+export {
+  storageUploadBodySchema,
+  storageUploadResponseSchema,
+  type StorageUploadBody,
+  type StorageUploadResponse,
+} from "./storage.js";
+export {
+  publicUserSchema,
+  updateUserBodySchema,
+  userUploadResultSchema,
+  executeHandlerBodySchema,
+  executeHandlerResponseSchema,
+  userPreferencesSchema,
+  userAvatarPresetSchema,
+  type UserAvatarPreset,
+  type PublicUser,
+  type UpdateUserBody,
+  type UserUploadResult,
+  type ExecuteHandlerBody,
+  type ExecuteHandlerResponse,
+} from "./user.js";
+export {
+  stardormChatJsonBodySchema,
+  stardormChatStructuredSchema,
+  stardormChatComputeSchema,
+  stardormChatRichRowSchema,
+  stardormChatRichBlockSchema,
+  x402SupportedAssetSchema,
+  stardormChatSuccessSchema,
+  stardormChatAttachmentSchema,
+  stardormChatClientErrorSchema,
+  stardormChatClientResultSchema,
+  type StardormChatJsonBody,
+  type StardormChatSuccess,
+  type StardormChatClientResult,
+  type StardormChatRichBlock,
+  type StardormChatAttachment,
+  type X402SupportedAsset,
+} from "./chat-api.js";
+export {
+  chatHistoryQuerySchema,
+  chatHistoryAttachmentSchema,
+  chatHistoryHandlerCtaSchema,
+  chatFollowUpSchema,
+  chatHistoryMessageSchema,
+  chatHistoryResponseSchema,
+  conversationSummarySchema,
+  conversationsQuerySchema,
+  conversationsPageResponseSchema,
+  conversationsListResponseSchema,
+  createConversationBodySchema,
+  deleteConversationResponseSchema,
+  type ChatHistoryQuery,
+  type ChatHistoryAttachment,
+  type ChatFollowUp,
+  type ChatHistoryMessage,
+  type ChatHistoryResponse,
+  type ConversationSummary,
+  type ConversationsQuery,
+  type ConversationsPageResponse,
+  type ConversationsListResponse,
+  type CreateConversationBody,
+  type DeleteConversationResponse,
+} from "./conversation.js";
+export {
+  agentOnchainFeedbackItemSchema,
+  agentFeedbacksQuerySchema,
+  agentFeedbacksPageResponseSchema,
+  type AgentOnchainFeedbackItem,
+  type AgentFeedbacksQuery,
+  type AgentFeedbacksPageResponse,
+} from "./agent-feedbacks.js";
+export {
+  paymentRequestTypeSchema,
+  paymentRequestStatusSchema,
+  paymentSettlementBodySchema,
+  publicPaymentRequestSchema,
+  mePaymentRequestsQuerySchema,
+  paymentRequestsListResponseSchema,
+  type PaymentSettlementBody,
+  type PublicPaymentRequest,
+  type MePaymentRequestsQuery,
+  type PaymentRequestsListResponse,
+} from "./payment-request.js";
+export {
+  onRampFormCtaParamsSchema,
+  onRampFormNetworkOptionSchema,
+  onRampTokensInputSchema,
+  onRampRecordSchema,
+  onRampRecordStatusSchema,
+  meOnRampsQuerySchema,
+  onRampsListResponseSchema,
+  isOnRampFormCtaParams,
+  type OnRampFormCtaParams,
+  type OnRampTokensInput,
+  type OnRampRecord,
+  type OnRampRecordStatus,
+  type MeOnRampsQuery,
+  type OnRampsListResponse,
+} from "./on-ramp.js";
+export {
+  stripeKycInputSchema,
+  userKycStatusSchema,
+  userKycStatusDocumentSchema,
+  type StripeKycInput,
+  type UserKycStatus,
+  type UserKycStatusDocument,
+} from "./kyc.js";
+export {
+  createCreditCardInputSchema,
+  creditCardFormCtaParamsSchema,
+  isCreditCardFormCtaParams,
+  creditCardPublicSchema,
+  creditCardSensitiveDetailsSchema,
+  creditCardsListResponseSchema,
+  creditCardFundBodySchema,
+  creditCardFundQuoteQuerySchema,
+  creditCardFundQuoteOffChainSchema,
+  creditCardFundQuoteOnChainSchema,
+  creditCardFundQuoteResponseSchema,
+  creditCardWithdrawBodySchema,
+  type CreateCreditCardInput,
+  type CreditCardFormCtaParams,
+  type CreditCardPublic,
+  type CreditCardSensitiveDetails,
+  type CreditCardsListResponse,
+  type CreditCardFundBody,
+  type CreditCardFundQuoteQuery,
+  type CreditCardFundQuoteResponse,
+  type CreditCardWithdrawBody,
+} from "./credit-card.js";
+export {
+  billingDatePartSchema,
+  billingDatePartToUtc,
+  billingRangeEndOfDay,
+  billingPeriodBounds,
+  generatePaymentInvoiceInputSchema,
+  generateFinancialActivityReportInputSchema,
+  type BillingDatePart,
+  type GeneratePaymentInvoiceInput,
+  type GenerateFinancialActivityReportInput,
+} from "./billing-handlers.js";
+export {
+  ISO_3166_1_ALPHA2_CODES,
+  isIso3166Alpha2,
+  isoCountryDisplayName,
+} from "./iso-3166-1-alpha2.js";
+export { taxRateForCountry } from "./tax-rate-for-country.js";
+export {
+  draftNativeTransferInputSchema,
+  draftErc20TransferInputSchema,
+  draftNftTransferInputSchema,
+  type DraftNativeTransferInput,
+  type DraftErc20TransferInput,
+  type DraftNftTransferInput,
+} from "./transfer-drafts.js";

package/src/iso-3166-1-alpha2.ts

@@ -0,0 +1,30 @@
+/**
+ * ISO 3166-1 alpha-2 codes (officially assigned), sourced from the slim-2 dataset
+ * (lukes/ISO-3166-Countries-with-Regional-Codes). UK is accepted as an alias for GB at validation boundaries.
+ */
+const ISO_3166_1_ALPHA2_CODES_RAW =
+  "AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW";
+
+export const ISO_3166_1_ALPHA2_CODES: readonly string[] = Object.freeze(
+  ISO_3166_1_ALPHA2_CODES_RAW.split(/\s+/),
+);
+
+const ISO_3166_1_ALPHA2_SET = new Set(ISO_3166_1_ALPHA2_CODES);
+
+export function isIso3166Alpha2(code: string): boolean {
+  const c = code.length === 2 ? code.toUpperCase() : "";
+  return ISO_3166_1_ALPHA2_SET.has(c);
+}
+
+export function isoCountryDisplayName(
+  code: string,
+  locale: string | string[] = "en",
+): string {
+  const c = code.length === 2 ? code.toUpperCase() : code;
+  try {
+    const dn = new Intl.DisplayNames(locale, { type: "region" });
+    return dn.of(c) ?? c;
+  } catch {
+    return c;
+  }
+}