@helium/blockchain-api 0.1.0

package/src/server/api/routers/welcomePacks/schemas.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { HotspotSchema } from "@/server/api/schemas";
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+export const ListInputSchema = z.object({
+  walletAddress: z.string().min(32),
+});
+
+export const RewardSplitInputSchema = z.object({
+  address: z.string(),
+  type: z.enum(["percentage", "fixed"]),
+  amount: z.number(),
+});
+
+export const ScheduleInputSchema = z.object({
+  frequency: z.enum(["daily", "weekly", "monthly"]),
+  time: z.string(),
+  timezone: z.string(),
+  dayOfWeek: z.string().optional(),
+  dayOfMonth: z.string().optional(),
+});
+
+export const CreateInputSchema = z.object({
+  walletAddress: z.string().min(32),
+  assetId: z.string(),
+  solAmount: z.number(),
+  rentRefund: z.string(),
+  assetReturnAddress: z.string(),
+  rewardsSplit: z.array(RewardSplitInputSchema),
+  schedule: ScheduleInputSchema,
+  lazyDistributor: z.string(),
+});
+
+export const GetInputSchema = z.object({
+  walletAddress: z.string().min(32),
+  packId: z.number(),
+});
+
+export const DeleteInputSchema = z.object({
+  walletAddress: z.string().min(32),
+  packId: z.number(),
+});
+
+export const GetByAddressInputSchema = z.object({
+  packAddress: z.string().min(32),
+});
+
+export const ClaimInputSchema = z.object({
+  packAddress: z.string().min(32),
+  walletAddress: z.string().min(32),
+  signature: z.string(),
+  expirationTs: z.string(),
+});
+
+export const InviteInputSchema = z.object({
+  packAddress: z.string().min(32),
+  walletAddress: z.string().min(32),
+  expirationDays: z.number().int().positive().max(365).default(7),
+});
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+export const WelcomePackSchema = z.object({
+  address: z.string(),
+  id: z.number(),
+  owner: z.string(),
+  asset: z.string(),
+  lazyDistributor: z.string(),
+  rewardsMint: z.string(),
+  rentRefund: z.string(),
+  solAmount: z.string(),
+  rewardsSplit: z.array(RewardSplitInputSchema),
+  rewardsSchedule: z.string(),
+  assetReturnAddress: z.string(),
+  bumpSeed: z.number(),
+  uniqueId: z.string(),
+  loading: z.boolean().optional(),
+  hotspot: HotspotSchema.nullable(),
+});
+
+export const ListOutputSchema = z.array(WelcomePackSchema);
+
+export const TransactionMetadataSchema = z
+  .object({
+    type: z.string(),
+    description: z.string(),
+  })
+  .catchall(z.unknown());
+
+export const TransactionItemSchema = z.object({
+  serializedTransaction: z.string(),
+  metadata: TransactionMetadataSchema.optional(),
+});
+
+export const TransactionDataSchema = z.object({
+  transactions: z.array(TransactionItemSchema),
+  parallel: z.boolean(),
+  tag: z.string().optional(),
+});
+
+export const CreateOutputSchema = z.object({
+  welcomePack: WelcomePackSchema,
+  transactionData: TransactionDataSchema,
+});
+
+export const DeleteOutputSchema = z.object({
+  transactionData: TransactionDataSchema,
+});
+
+export const ClaimOutputSchema = z.object({
+  transactionData: TransactionDataSchema,
+});
+
+export const InviteOutputSchema = z.object({
+  message: z.string(),
+  expirationTs: z.number(),
+});
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type ListInput = z.infer<typeof ListInputSchema>;
+export type CreateInput = z.infer<typeof CreateInputSchema>;
+export type GetInput = z.infer<typeof GetInputSchema>;
+export type DeleteInput = z.infer<typeof DeleteInputSchema>;
+export type GetByAddressInput = z.infer<typeof GetByAddressInputSchema>;
+export type ClaimInput = z.infer<typeof ClaimInputSchema>;
+export type InviteInput = z.infer<typeof InviteInputSchema>;
+export type WelcomePack = z.infer<typeof WelcomePackSchema>;

package/src/server/api/schemas.ts

@@ -0,0 +1,281 @@
+import { z } from "zod";
+
+// ============================================================================
+// Common Transaction Schemas
+// ============================================================================
+
+/**
+ * Metadata associated with a transaction for tracking and display purposes.
+ */
+export const TransactionMetadataSchema = z
+  .object({
+    type: z.string(),
+    description: z.string(),
+  })
+  .catchall(z.unknown());
+
+/**
+ * A single transaction item with serialized data and optional metadata.
+ */
+export const TransactionItemSchema = z.object({
+  serializedTransaction: z.string(),
+  metadata: TransactionMetadataSchema.optional(),
+});
+
+/**
+ * Transaction data returned by procedures that create transactions.
+ * Contains serialized transactions ready for signing and submission.
+ */
+export const TransactionDataSchema = z.object({
+  transactions: z.array(TransactionItemSchema),
+  parallel: z.boolean(),
+  tag: z.string().optional(),
+});
+
+/**
+ * Request schema for submitting a batch of transactions.
+ */
+export const TransactionBatchRequestSchema = z.object({
+  transactions: z.array(TransactionItemSchema),
+  parallel: z.boolean(),
+  tag: z.string().optional(),
+});
+
+/**
+ * Response schema for transaction batch submission.
+ */
+export const TransactionBatchResponseSchema = z.object({
+  batchId: z.string(),
+  message: z.string().optional(),
+});
+
+// ============================================================================
+// Common Response Schemas
+// ============================================================================
+
+/**
+ * Standard error response schema.
+ */
+export const ErrorResponseSchema = z.object({
+  error: z.string(),
+  details: z.array(z.string()).optional(),
+});
+
+// ============================================================================
+// Wallet Address Schema
+// ============================================================================
+
+/**
+ * Solana wallet address validation.
+ */
+export const WalletAddressSchema = z.string().min(32).max(44);
+
+/**
+ * Solana public key validation (base58 encoded).
+ */
+export const PublicKeySchema = z.string().min(32).max(44);
+
+// ============================================================================
+// Pagination Schemas
+// ============================================================================
+
+/**
+ * Standard pagination input schema.
+ */
+export const PaginationInputSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+});
+
+/**
+ * Standard pagination output schema.
+ */
+export const PaginationOutputSchema = z.object({
+  total: z.number(),
+  page: z.number(),
+  totalPages: z.number(),
+});
+
+// ============================================================================
+// Hotspot Schemas
+// ============================================================================
+
+/**
+ * Hotspot type enumeration.
+ */
+export const HotspotTypeSchema = z.enum(["iot", "mobile", "all"]);
+
+/**
+ * Hotspot device type enumeration.
+ */
+export const DeviceTypeSchema = z.enum([
+  "iot-gateway",
+  "wifiIndoor",
+  "wifiOutdoor",
+  "wifiDataOnly",
+  "cbrs",
+]);
+
+/**
+ * Hotspot ownership type enumeration.
+ */
+export const OwnershipTypeSchema = z.enum(["owner", "direct", "fanout", "all"]);
+
+/**
+ * Hotspot share configuration.
+ */
+export const HotspotSharesSchema = z.object({
+  fixed: z.string().optional(),
+  percentage: z.number().optional(),
+});
+
+/**
+ * Complete hotspot data schema.
+ */
+export const HotspotSchema = z.object({
+  address: z.string(),
+  entityKey: z.string(),
+  name: z.string(),
+  type: HotspotTypeSchema,
+  deviceType: DeviceTypeSchema,
+  city: z.string().optional(),
+  state: z.string().optional(),
+  country: z.string().optional(),
+  asset: z.string(),
+  isOnline: z.boolean().optional(),
+  owner: z.string().optional(),
+  shares: HotspotSharesSchema.optional(),
+  ownershipType: z.string(),
+});
+
+/**
+ * Paginated hotspots response schema.
+ */
+export const HotspotsDataSchema = z.object({
+  hotspots: z.array(HotspotSchema),
+  total: z.number(),
+  page: z.number(),
+  totalPages: z.number(),
+});
+
+// ============================================================================
+// Token Schemas
+// ============================================================================
+
+/**
+ * Token account data schema.
+ */
+export const TokenAccountSchema = z.object({
+  mint: z.string(),
+  address: z.string(),
+  balance: z.string(),
+  decimals: z.number(),
+  uiAmount: z.number(),
+  symbol: z.string().optional(),
+  name: z.string().optional(),
+  logoURI: z.string().optional(),
+  priceUsd: z.number().optional(),
+  balanceUsd: z.number().optional(),
+});
+
+/**
+ * Token balance data response schema.
+ */
+export const TokenBalanceDataSchema = z.object({
+  totalBalanceUsd: z.number(),
+  solBalance: z.number(),
+  solBalanceUsd: z.number(),
+  tokens: z.array(TokenAccountSchema),
+});
+
+// ============================================================================
+// Welcome Pack Schemas
+// ============================================================================
+
+/**
+ * Reward split recipient schema.
+ */
+export const RewardSplitSchema = z.object({
+  address: z.string(),
+  type: z.enum(["percentage", "fixed"]),
+  amount: z.number(),
+});
+
+/**
+ * Schedule configuration schema.
+ */
+export const ScheduleSchema = z.object({
+  frequency: z.enum(["daily", "weekly", "monthly"]),
+  time: z.string(),
+  timezone: z.string(),
+  dayOfWeek: z.string().optional(),
+  dayOfMonth: z.string().optional(),
+});
+
+/**
+ * Welcome pack with status schema.
+ */
+export const WelcomePackWithStatusSchema = z.object({
+  address: z.string(),
+  id: z.number(),
+  owner: z.string(),
+  asset: z.string(),
+  lazyDistributor: z.string(),
+  rewardsMint: z.string(),
+  rentRefund: z.string(),
+  solAmount: z.string(),
+  rewardsSplit: z.array(RewardSplitSchema),
+  rewardsSchedule: z.string(),
+  assetReturnAddress: z.string(),
+  bumpSeed: z.number(),
+  uniqueId: z.string(),
+  loading: z.boolean().optional(),
+});
+
+// ============================================================================
+// Split Schemas
+// ============================================================================
+
+/**
+ * Split share schema.
+ */
+export const SplitShareSchema = z.object({
+  wallet: z.string(),
+  delegate: z.string(),
+  fixed: z.number(),
+  shares: z.number(),
+});
+
+/**
+ * Split response schema.
+ */
+export const SplitResponseSchema = z.object({
+  walletAddress: z.string(),
+  hotspotPubkey: z.string(),
+  splitAddress: z.string(),
+  shares: z.array(SplitShareSchema),
+});
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type TransactionMetadata = z.infer<typeof TransactionMetadataSchema>;
+export type TransactionItem = z.infer<typeof TransactionItemSchema>;
+export type TransactionData = z.infer<typeof TransactionDataSchema>;
+export type TransactionBatchRequest = z.infer<
+  typeof TransactionBatchRequestSchema
+>;
+export type TransactionBatchResponse = z.infer<
+  typeof TransactionBatchResponseSchema
+>;
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+export type Hotspot = z.infer<typeof HotspotSchema>;
+export type HotspotsData = z.infer<typeof HotspotsDataSchema>;
+export type TokenAccount = z.infer<typeof TokenAccountSchema>;
+export type TokenBalanceData = z.infer<typeof TokenBalanceDataSchema>;
+export type RewardSplit = z.infer<typeof RewardSplitSchema>;
+export type Schedule = z.infer<typeof ScheduleSchema>;
+export type WelcomePackWithStatus = z.infer<typeof WelcomePackWithStatusSchema>;
+export type SplitShare = z.infer<typeof SplitShareSchema>;
+export type SplitResponse = z.infer<typeof SplitResponseSchema>;

package/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "sourceMap": true,
+    "inlineSourceMap": false,
+    "inlineSources": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    ".next/dev/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/types/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Type exports for @helium/blockchain-api
+ *
+ * This module exports the ORPC router types that can be used by external packages
+ * to get full type safety when working with the blockchain API.
+ *
+ * @example
+ * ```typescript
+ * import type { BlockchainAPIClient, ORPCRouter } from "@helium/blockchain-api"
+ * import { createORPCClient } from "@orpc/client"
+ *
+ * const client: BlockchainAPIClient = createORPCClient(link)
+ * ```
+ */
+
+import { RouterClient } from "@orpc/server";
+
+// Re-export the router type
+export type { ORPCRouter } from "../src/server/api";
+
+// Re-export RouterClient type for convenience
+export type { RouterClient } from "@orpc/server";
+
+// Export a helper type for creating typed clients
+export type BlockchainAPIClient = RouterClient<
+  import("../src/server/api").ORPCRouter
+>;