@alien_org/contract 0.0.17-beta

package/README.md

@@ -0,0 +1,105 @@
+# @alien_org/contract
+
+Type definitions and version utilities for miniapp-host communication.
+
+## Installation
+
+```bash
+bun add @alien_org/contract
+```
+
+## Exports
+
+### Types
+
+```typescript
+import type {
+  // Method types
+  Methods,                        // Interface of all methods
+  MethodName,                     // Union of method names
+  MethodPayload,                  // Payload type for a method
+  CreateMethodPayload,            // Helper for defining methods
+  MethodNameWithVersionedPayload, // Methods with versioned payloads
+  MethodVersionedPayload,         // Versioned payload for a method
+
+  // Event types
+  Events,               // Interface of all events
+  EventName,            // Union of event names
+  EventPayload,         // Payload type for an event
+  CreateEventPayload,   // Helper for defining events
+
+  // Launch parameters
+  LaunchParams,         // Host-injected params (authToken, contractVersion, etc.)
+  Platform,             // 'ios' | 'android'
+
+  // Utilities
+  Version,              // Semantic version string type
+} from '@alien_org/contract';
+```
+
+### Constants
+
+```typescript
+import { PLATFORMS, releases } from '@alien_org/contract';
+
+PLATFORMS  // ['ios', 'android']
+releases   // Record<Version, MethodName[]> - version to methods mapping
+```
+
+### Version Utilities
+
+```typescript
+import {
+  isMethodSupported,
+  getMethodMinVersion,
+  getReleaseVersion,
+} from '@alien_org/contract';
+
+// Check if method is supported in a version
+isMethodSupported('app:ready', '0.0.9');         // true
+isMethodSupported('payment:request', '0.0.9');   // false
+
+// Get minimum version that supports a method
+getMethodMinVersion('app:ready');         // '0.0.9'
+getMethodMinVersion('payment:request');   // '0.0.14'
+
+// Get version where a method was introduced
+getReleaseVersion('app:ready');           // '0.0.9'
+```
+
+## Available Methods
+
+| Method | Since | Description |
+|--------|-------|-------------|
+| `app:ready` | 0.0.9 | Notify host that miniapp is ready |
+| `miniapp:close.ack` | 0.0.14 | Acknowledge close request |
+| `host.back.button:toggle` | 0.0.14 | Show/hide back button |
+| `payment:request` | 0.0.14 | Request payment |
+
+## Available Events
+
+| Event | Since | Description |
+|-------|-------|-------------|
+| `miniapp:close` | 0.0.14 | Host is closing miniapp |
+| `host.back.button:clicked` | 0.0.14 | Back button was clicked |
+| `payment:response` | 0.0.14 | Payment result |
+
+## LaunchParams
+
+Parameters injected by the host app:
+
+```typescript
+interface LaunchParams {
+  authToken: string | undefined;        // JWT auth token
+  contractVersion: Version | undefined; // Host's contract version
+  hostAppVersion: string | undefined;   // Host app version
+  platform: Platform | undefined;       // 'ios' | 'android'
+  startParam: string | undefined;       // Custom param (referrals, etc.)
+}
+```
+
+## Adding New Methods/Events
+
+1. Define in `src/methods/definitions/methods.ts` or `src/events/definitions/events.ts`
+2. Add version mapping in `src/methods/versions/releases.ts`
+3. Build: `bun run build`

package/dist/index.cjs

@@ -0,0 +1,70 @@
+
+//#region src/launch-params.ts
+/**
+* Supported platforms for miniapps.
+*/
+const PLATFORMS = ["ios", "android"];
+
+//#endregion
+//#region src/methods/versions/releases.ts
+const releases = {
+	"0.0.9": ["app:ready"],
+	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"]
+};
+
+//#endregion
+//#region src/methods/versions/get-release-version.ts
+function getReleaseVersion(method, payload) {
+	return Object.keys(releases).find((version) => {
+		const releaseItems = releases[version];
+		if (!releaseItems) return false;
+		return releaseItems.some((item) => {
+			if (payload) return typeof item === "object" && item.method === method && item.param === payload;
+			return item === method;
+		});
+	}) || null;
+}
+
+//#endregion
+//#region src/methods/versions/index.ts
+/**
+* Check if a method is supported in a given version.
+*
+* @param method - The method name to check.
+* @param version - The contract version (must be a valid version string, not undefined).
+* @returns `true` if the method is supported in the given version, `false` otherwise.
+*
+* @remarks
+* This function only accepts valid version strings. Version existence checks should be
+* handled at a higher level before calling this function.
+*/
+function isMethodSupported(method, version) {
+	const methods = releases[version];
+	if (!methods) return false;
+	return methods.some((m) => typeof m === "string" ? m === method : m.method === method);
+}
+/**
+* Get the minimum version that supports a method.
+* Returns undefined if method not found in any version.
+*/
+function getMethodMinVersion(method) {
+	const sorted = Object.keys(releases).sort((a, b) => {
+		const [aMajor, aMinor, aPatch] = a.split(".").map(Number);
+		const [bMajor, bMinor, bPatch] = b.split(".").map(Number);
+		if (aMajor !== bMajor) return (aMajor ?? 0) - (bMajor ?? 0);
+		if (aMinor !== bMinor) return (aMinor ?? 0) - (bMinor ?? 0);
+		return (aPatch ?? 0) - (bPatch ?? 0);
+	});
+	for (const version of sorted) {
+		const methods = releases[version];
+		if (!methods) continue;
+		if (methods.some((m) => typeof m === "string" ? m === method : m.method === method)) return version;
+	}
+}
+
+//#endregion
+exports.PLATFORMS = PLATFORMS;
+exports.getMethodMinVersion = getMethodMinVersion;
+exports.getReleaseVersion = getReleaseVersion;
+exports.isMethodSupported = isMethodSupported;
+exports.releases = releases;

package/dist/index.d.cts

@@ -0,0 +1,323 @@
+//#region src/utils.d.ts
+/**
+ * Adds a reqId field to the payload.
+ * @schema
+ */
+type WithReqId<T> = T & {
+  /**
+   * Request identifier.
+   * @schema
+   */
+  reqId: string;
+};
+/**
+ * Semantic versioning type.
+ * @example
+ * type Version = '1.0.0';
+ */
+type Version = `${number}.${number}.${number}`;
+/**
+ * Extracts keys, that are present in the type if it is an object.
+ * @example
+ * type Keys = UnionKeys<{ a: string, b: number }>;
+ * // Keys = 'a' | 'b'
+ */
+type UnionKeys<T> = T extends T ? keyof T : never;
+/**
+ * Checks if a type is never.
+ * @example
+ * type IsNever = IsNever<never>;
+ * // IsNever = true
+ */
+type IsNever<T> = [T] extends [never] ? true : false;
+/**
+ * Conditional type.
+ * @example
+ * type If = If<true, 'true', 'false'>;
+ * // If = 'true'
+ */
+type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
+/**
+ * Empty object type.
+ * @example
+ * type Empty = Empty;
+ * // Empty = {}
+ */
+type Empty = Record<string, never>;
+//#endregion
+//#region src/events/types/payload.d.ts
+/**
+ * Creates event payload types.
+ */
+interface CreateEventPayload<Payload = never> {
+  payload: Payload;
+}
+//#endregion
+//#region src/events/definitions/events.d.ts
+/**
+ * Events interface defining all available events and their payloads.
+ * @since 0.0.1
+ * @schema
+ */
+interface Events {
+  /**
+   * Miniapp close event, fired by the host app just before the miniapp is closed.
+   * @since 0.0.14
+   * @schema
+   */
+  'miniapp:close': CreateEventPayload<Empty>;
+  /**
+   * Host app's back button clicked event.
+   * @since 0.0.14
+   * @schema
+   */
+  'host.back.button:clicked': CreateEventPayload<Empty>;
+  /**
+   * Payment response event.
+   *
+   * Statuses:
+   * - `paid`: Payment successful, `txHash` included
+   * - `cancelled`: User manually cancelled/rejected the payment
+   * - `failed`: Error occurred (see `errorCode` for details)
+   *
+   * For instant fulfillment, your backend should fulfill on webhook receipt
+   * using the `invoice` from the request.
+   *
+   * @since 0.0.14
+   * @schema
+   */
+  'payment:response': CreateEventPayload<WithReqId<{
+    /**
+     * Payment status.
+     * - `paid`: Success
+     * - `cancelled`: User rejected
+     * - `failed`: Error (check `errorCode`)
+     * @since 0.0.14
+     * @schema
+     */
+    status: 'paid' | 'cancelled' | 'failed';
+    /**
+     * Transaction hash (present when status is 'paid').
+     * @since 0.0.14
+     * @schema
+     */
+    txHash?: string;
+    /**
+     * Error code (present when status is 'failed').
+     * - `insufficient_balance`: User doesn't have enough tokens
+     * - `network_error`: Blockchain network issue
+     * - `pre_checkout_rejected`: Backend rejected the payment in pre-checkout
+     * - `pre_checkout_timeout`: Backend didn't respond to pre-checkout in time
+     * - `unknown`: Unexpected error
+     * @since 0.0.14
+     * @schema
+     */
+    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+  }>>;
+}
+//#endregion
+//#region src/events/types/event-types.d.ts
+type EventName = keyof Events;
+type EventPayload<E extends EventName> = Events[E]['payload'];
+//#endregion
+//#region src/launch-params.d.ts
+/**
+ * Supported platforms for miniapps.
+ */
+declare const PLATFORMS: readonly ["ios", "android"];
+/**
+ * Platform the miniapp is running on.
+ */
+type Platform = (typeof PLATFORMS)[number];
+/**
+ * Launch parameters injected by the host app.
+ */
+interface LaunchParams {
+  /** JWT auth token injected by host app */
+  authToken: string | undefined;
+  /** Contract version supported by host app (semver) */
+  contractVersion: Version | undefined;
+  /** Host app version (e.g., '1.2.3') */
+  hostAppVersion: string | undefined;
+  /** Platform the miniapp is running on */
+  platform: Platform | undefined;
+  /**
+   * Custom start parameter injected by host app.
+   * Used for referral codes, campaign tracking, or custom routing.
+   */
+  startParam: string | undefined;
+}
+//#endregion
+//#region src/methods/types/payload.d.ts
+/**
+ * Creates method payload types.
+ */
+interface CreateMethodPayload<Payload = never, VersionedPayload extends UnionKeys<Payload> = never> {
+  payload: Payload;
+  versionedPayload: VersionedPayload;
+}
+//#endregion
+//#region src/methods/definitions/methods.d.ts
+/**
+ * Methods interface defining all available methods and their payloads.
+ * @schema
+ */
+interface Methods {
+  /**
+   * Miniapp ready method.
+   * Sent by the miniapp to notify the host app that it has loaded and is ready to be displayed.
+   * @since 0.0.1
+   * @schema
+   */
+  'app:ready': CreateMethodPayload<Empty>;
+  /**
+   * Miniapp close acknowledgment method.
+   * Sent by the miniapp to notify the host app that it has completed cleanup and is ready to be closed.
+   * Note that if the miniapp takes longer than 10 seconds to close, the host app will force close the miniapp.
+   * @since 0.0.14
+   * @schema
+   */
+  'miniapp:close.ack': CreateMethodPayload<Empty>;
+  /**
+   * Toggle host app's back button visibility.
+   * @since 0.0.14
+   * @schema
+   */
+  'host.back.button:toggle': CreateMethodPayload<{
+    /**
+     * Whether to show or hide the back button.
+     * @since 0.0.14
+     * @schema
+     */
+    visible: boolean;
+  }>;
+  /**
+   * Request a payment from the user.
+   *
+   * The `invoice` field is your order/invoice ID for backend correlation.
+   * Your backend receives a webhook when user pays - fulfill the order
+   * immediately without waiting for chain confirmation.
+   *
+   * Optional display fields (`title`, `caption`, `iconUrl`, `quantity`)
+   * are shown on the payment approval screen.
+   *
+   * Set `test: true` for test mode - no real payment is made, but webhooks
+   * are fired with `test: true` flag. Use for development and testing.
+   *
+   * @since 0.0.14
+   * @schema
+   */
+  'payment:request': CreateMethodPayload<WithReqId<{
+    /**
+     * The recipient's wallet address.
+     * @since 0.0.14
+     * @schema
+     */
+    recipient: string;
+    /**
+     * The amount to pay (in token's smallest unit, as string for precision).
+     * @since 0.0.14
+     * @schema
+     */
+    amount: string;
+    /**
+     * The token identifier (e.g., 'SOL', 'ALIEN', or contract address).
+     * @since 0.0.14
+     * @schema
+     */
+    token: string;
+    /**
+     * The network for the payment ('solana' or 'alien').
+     * @since 0.0.14
+     * @schema
+     */
+    network: string;
+    /**
+     * Your order/invoice ID for backend correlation and instant fulfillment.
+     * @since 0.0.14
+     * @schema
+     */
+    invoice: string;
+    /**
+     * Item title shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    title?: string;
+    /**
+     * Item description/caption shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    caption?: string;
+    /**
+     * Item icon URL shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    iconUrl?: string;
+    /**
+     * Quantity of items being purchased.
+     * @since 0.0.14
+     * @schema
+     */
+    quantity?: number;
+    /**
+     * Test mode flag. When true, no real payment is processed.
+     * The approval screen shows a test indicator, and webhooks
+     * include `test: true`. Use for development and testing.
+     * @since 0.0.14
+     * @schema
+     */
+    test?: boolean;
+  }>>;
+}
+//#endregion
+//#region src/methods/types/method-types.d.ts
+type MethodName = keyof Methods;
+type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
+/**
+ * Method names which have versioned payload.
+ */
+type MethodNameWithVersionedPayload = { [M in MethodName]: If<IsNever<Methods[M]['versionedPayload']>, never, M> }[MethodName];
+/**
+ * Method payload which appear only in the specific version.
+ */
+type MethodVersionedPayload<M$1 extends MethodNameWithVersionedPayload> = Methods[M$1]['versionedPayload'];
+//#endregion
+//#region src/methods/versions/get-release-version.d.ts
+/**
+ * @returns Version of the specified method parameter release. Returns `null`
+ * if passed method or parameter are unknown.
+ * @param method - method name
+ * @param param - method parameter
+ */
+declare function getReleaseVersion<M$1 extends MethodNameWithVersionedPayload>(method: M$1, payload: MethodVersionedPayload<M$1>): Version | null;
+declare function getReleaseVersion(method: MethodName): Version | null;
+//#endregion
+//#region src/methods/versions/releases.d.ts
+declare const releases: Record<Version, (MethodName | {
+  method: MethodNameWithVersionedPayload;
+  param: MethodVersionedPayload<MethodNameWithVersionedPayload>;
+})[]>;
+//#endregion
+//#region src/methods/versions/index.d.ts
+/**
+ * Check if a method is supported in a given version.
+ *
+ * @param method - The method name to check.
+ * @param version - The contract version (must be a valid version string, not undefined).
+ * @returns `true` if the method is supported in the given version, `false` otherwise.
+ *
+ * @remarks
+ * This function only accepts valid version strings. Version existence checks should be
+ * handled at a higher level before calling this function.
+ */
+declare function isMethodSupported(method: MethodName, version: Version): boolean;
+/**
+ * Get the minimum version that supports a method.
+ * Returns undefined if method not found in any version.
+ */
+declare function getMethodMinVersion(method: MethodName): Version | undefined;
+//#endregion
+export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/dist/index.d.mts

@@ -0,0 +1,323 @@
+//#region src/utils.d.ts
+/**
+ * Adds a reqId field to the payload.
+ * @schema
+ */
+type WithReqId<T> = T & {
+  /**
+   * Request identifier.
+   * @schema
+   */
+  reqId: string;
+};
+/**
+ * Semantic versioning type.
+ * @example
+ * type Version = '1.0.0';
+ */
+type Version = `${number}.${number}.${number}`;
+/**
+ * Extracts keys, that are present in the type if it is an object.
+ * @example
+ * type Keys = UnionKeys<{ a: string, b: number }>;
+ * // Keys = 'a' | 'b'
+ */
+type UnionKeys<T> = T extends T ? keyof T : never;
+/**
+ * Checks if a type is never.
+ * @example
+ * type IsNever = IsNever<never>;
+ * // IsNever = true
+ */
+type IsNever<T> = [T] extends [never] ? true : false;
+/**
+ * Conditional type.
+ * @example
+ * type If = If<true, 'true', 'false'>;
+ * // If = 'true'
+ */
+type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
+/**
+ * Empty object type.
+ * @example
+ * type Empty = Empty;
+ * // Empty = {}
+ */
+type Empty = Record<string, never>;
+//#endregion
+//#region src/events/types/payload.d.ts
+/**
+ * Creates event payload types.
+ */
+interface CreateEventPayload<Payload = never> {
+  payload: Payload;
+}
+//#endregion
+//#region src/events/definitions/events.d.ts
+/**
+ * Events interface defining all available events and their payloads.
+ * @since 0.0.1
+ * @schema
+ */
+interface Events {
+  /**
+   * Miniapp close event, fired by the host app just before the miniapp is closed.
+   * @since 0.0.14
+   * @schema
+   */
+  'miniapp:close': CreateEventPayload<Empty>;
+  /**
+   * Host app's back button clicked event.
+   * @since 0.0.14
+   * @schema
+   */
+  'host.back.button:clicked': CreateEventPayload<Empty>;
+  /**
+   * Payment response event.
+   *
+   * Statuses:
+   * - `paid`: Payment successful, `txHash` included
+   * - `cancelled`: User manually cancelled/rejected the payment
+   * - `failed`: Error occurred (see `errorCode` for details)
+   *
+   * For instant fulfillment, your backend should fulfill on webhook receipt
+   * using the `invoice` from the request.
+   *
+   * @since 0.0.14
+   * @schema
+   */
+  'payment:response': CreateEventPayload<WithReqId<{
+    /**
+     * Payment status.
+     * - `paid`: Success
+     * - `cancelled`: User rejected
+     * - `failed`: Error (check `errorCode`)
+     * @since 0.0.14
+     * @schema
+     */
+    status: 'paid' | 'cancelled' | 'failed';
+    /**
+     * Transaction hash (present when status is 'paid').
+     * @since 0.0.14
+     * @schema
+     */
+    txHash?: string;
+    /**
+     * Error code (present when status is 'failed').
+     * - `insufficient_balance`: User doesn't have enough tokens
+     * - `network_error`: Blockchain network issue
+     * - `pre_checkout_rejected`: Backend rejected the payment in pre-checkout
+     * - `pre_checkout_timeout`: Backend didn't respond to pre-checkout in time
+     * - `unknown`: Unexpected error
+     * @since 0.0.14
+     * @schema
+     */
+    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+  }>>;
+}
+//#endregion
+//#region src/events/types/event-types.d.ts
+type EventName = keyof Events;
+type EventPayload<E extends EventName> = Events[E]['payload'];
+//#endregion
+//#region src/launch-params.d.ts
+/**
+ * Supported platforms for miniapps.
+ */
+declare const PLATFORMS: readonly ["ios", "android"];
+/**
+ * Platform the miniapp is running on.
+ */
+type Platform = (typeof PLATFORMS)[number];
+/**
+ * Launch parameters injected by the host app.
+ */
+interface LaunchParams {
+  /** JWT auth token injected by host app */
+  authToken: string | undefined;
+  /** Contract version supported by host app (semver) */
+  contractVersion: Version | undefined;
+  /** Host app version (e.g., '1.2.3') */
+  hostAppVersion: string | undefined;
+  /** Platform the miniapp is running on */
+  platform: Platform | undefined;
+  /**
+   * Custom start parameter injected by host app.
+   * Used for referral codes, campaign tracking, or custom routing.
+   */
+  startParam: string | undefined;
+}
+//#endregion
+//#region src/methods/types/payload.d.ts
+/**
+ * Creates method payload types.
+ */
+interface CreateMethodPayload<Payload = never, VersionedPayload extends UnionKeys<Payload> = never> {
+  payload: Payload;
+  versionedPayload: VersionedPayload;
+}
+//#endregion
+//#region src/methods/definitions/methods.d.ts
+/**
+ * Methods interface defining all available methods and their payloads.
+ * @schema
+ */
+interface Methods {
+  /**
+   * Miniapp ready method.
+   * Sent by the miniapp to notify the host app that it has loaded and is ready to be displayed.
+   * @since 0.0.1
+   * @schema
+   */
+  'app:ready': CreateMethodPayload<Empty>;
+  /**
+   * Miniapp close acknowledgment method.
+   * Sent by the miniapp to notify the host app that it has completed cleanup and is ready to be closed.
+   * Note that if the miniapp takes longer than 10 seconds to close, the host app will force close the miniapp.
+   * @since 0.0.14
+   * @schema
+   */
+  'miniapp:close.ack': CreateMethodPayload<Empty>;
+  /**
+   * Toggle host app's back button visibility.
+   * @since 0.0.14
+   * @schema
+   */
+  'host.back.button:toggle': CreateMethodPayload<{
+    /**
+     * Whether to show or hide the back button.
+     * @since 0.0.14
+     * @schema
+     */
+    visible: boolean;
+  }>;
+  /**
+   * Request a payment from the user.
+   *
+   * The `invoice` field is your order/invoice ID for backend correlation.
+   * Your backend receives a webhook when user pays - fulfill the order
+   * immediately without waiting for chain confirmation.
+   *
+   * Optional display fields (`title`, `caption`, `iconUrl`, `quantity`)
+   * are shown on the payment approval screen.
+   *
+   * Set `test: true` for test mode - no real payment is made, but webhooks
+   * are fired with `test: true` flag. Use for development and testing.
+   *
+   * @since 0.0.14
+   * @schema
+   */
+  'payment:request': CreateMethodPayload<WithReqId<{
+    /**
+     * The recipient's wallet address.
+     * @since 0.0.14
+     * @schema
+     */
+    recipient: string;
+    /**
+     * The amount to pay (in token's smallest unit, as string for precision).
+     * @since 0.0.14
+     * @schema
+     */
+    amount: string;
+    /**
+     * The token identifier (e.g., 'SOL', 'ALIEN', or contract address).
+     * @since 0.0.14
+     * @schema
+     */
+    token: string;
+    /**
+     * The network for the payment ('solana' or 'alien').
+     * @since 0.0.14
+     * @schema
+     */
+    network: string;
+    /**
+     * Your order/invoice ID for backend correlation and instant fulfillment.
+     * @since 0.0.14
+     * @schema
+     */
+    invoice: string;
+    /**
+     * Item title shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    title?: string;
+    /**
+     * Item description/caption shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    caption?: string;
+    /**
+     * Item icon URL shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    iconUrl?: string;
+    /**
+     * Quantity of items being purchased.
+     * @since 0.0.14
+     * @schema
+     */
+    quantity?: number;
+    /**
+     * Test mode flag. When true, no real payment is processed.
+     * The approval screen shows a test indicator, and webhooks
+     * include `test: true`. Use for development and testing.
+     * @since 0.0.14
+     * @schema
+     */
+    test?: boolean;
+  }>>;
+}
+//#endregion
+//#region src/methods/types/method-types.d.ts
+type MethodName = keyof Methods;
+type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
+/**
+ * Method names which have versioned payload.
+ */
+type MethodNameWithVersionedPayload = { [M in MethodName]: If<IsNever<Methods[M]['versionedPayload']>, never, M> }[MethodName];
+/**
+ * Method payload which appear only in the specific version.
+ */
+type MethodVersionedPayload<M$1 extends MethodNameWithVersionedPayload> = Methods[M$1]['versionedPayload'];
+//#endregion
+//#region src/methods/versions/get-release-version.d.ts
+/**
+ * @returns Version of the specified method parameter release. Returns `null`
+ * if passed method or parameter are unknown.
+ * @param method - method name
+ * @param param - method parameter
+ */
+declare function getReleaseVersion<M$1 extends MethodNameWithVersionedPayload>(method: M$1, payload: MethodVersionedPayload<M$1>): Version | null;
+declare function getReleaseVersion(method: MethodName): Version | null;
+//#endregion
+//#region src/methods/versions/releases.d.ts
+declare const releases: Record<Version, (MethodName | {
+  method: MethodNameWithVersionedPayload;
+  param: MethodVersionedPayload<MethodNameWithVersionedPayload>;
+})[]>;
+//#endregion
+//#region src/methods/versions/index.d.ts
+/**
+ * Check if a method is supported in a given version.
+ *
+ * @param method - The method name to check.
+ * @param version - The contract version (must be a valid version string, not undefined).
+ * @returns `true` if the method is supported in the given version, `false` otherwise.
+ *
+ * @remarks
+ * This function only accepts valid version strings. Version existence checks should be
+ * handled at a higher level before calling this function.
+ */
+declare function isMethodSupported(method: MethodName, version: Version): boolean;
+/**
+ * Get the minimum version that supports a method.
+ * Returns undefined if method not found in any version.
+ */
+declare function getMethodMinVersion(method: MethodName): Version | undefined;
+//#endregion
+export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/dist/index.mjs

@@ -0,0 +1,65 @@
+//#region src/launch-params.ts
+/**
+* Supported platforms for miniapps.
+*/
+const PLATFORMS = ["ios", "android"];
+
+//#endregion
+//#region src/methods/versions/releases.ts
+const releases = {
+	"0.0.9": ["app:ready"],
+	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"]
+};
+
+//#endregion
+//#region src/methods/versions/get-release-version.ts
+function getReleaseVersion(method, payload) {
+	return Object.keys(releases).find((version) => {
+		const releaseItems = releases[version];
+		if (!releaseItems) return false;
+		return releaseItems.some((item) => {
+			if (payload) return typeof item === "object" && item.method === method && item.param === payload;
+			return item === method;
+		});
+	}) || null;
+}
+
+//#endregion
+//#region src/methods/versions/index.ts
+/**
+* Check if a method is supported in a given version.
+*
+* @param method - The method name to check.
+* @param version - The contract version (must be a valid version string, not undefined).
+* @returns `true` if the method is supported in the given version, `false` otherwise.
+*
+* @remarks
+* This function only accepts valid version strings. Version existence checks should be
+* handled at a higher level before calling this function.
+*/
+function isMethodSupported(method, version) {
+	const methods = releases[version];
+	if (!methods) return false;
+	return methods.some((m) => typeof m === "string" ? m === method : m.method === method);
+}
+/**
+* Get the minimum version that supports a method.
+* Returns undefined if method not found in any version.
+*/
+function getMethodMinVersion(method) {
+	const sorted = Object.keys(releases).sort((a, b) => {
+		const [aMajor, aMinor, aPatch] = a.split(".").map(Number);
+		const [bMajor, bMinor, bPatch] = b.split(".").map(Number);
+		if (aMajor !== bMajor) return (aMajor ?? 0) - (bMajor ?? 0);
+		if (aMinor !== bMinor) return (aMinor ?? 0) - (bMinor ?? 0);
+		return (aPatch ?? 0) - (bPatch ?? 0);
+	});
+	for (const version of sorted) {
+		const methods = releases[version];
+		if (!methods) continue;
+		if (methods.some((m) => typeof m === "string" ? m === method : m.method === method)) return version;
+	}
+}
+
+//#endregion
+export { PLATFORMS, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@alien_org/contract",
+  "version": "0.0.17-beta",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alien-id/miniapp-sdk.git",
+    "directory": "packages/contract"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "bun test tests",
+    "prepublishOnly": "bun run build",
+    "generate-schemas": "bun run scripts/generate-schemas.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "@types/node": "^25.0.3",
+    "tsdown": "^0.18.1",
+    "typescript-json-schema": "^0.67.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}