@farcaster/miniapp-core 0.0.0-canary-20250630212339

package/esm/actions/index.js

@@ -0,0 +1,10 @@
+export * as AddMiniApp from "./AddMiniApp.js";
+export * as ComposeCast from "./ComposeCast.js";
+export * as Haptics from "./Haptics.js";
+export * as Ready from "./Ready.js";
+export * as SignIn from "./SignIn.js";
+export * as SendToken from "./SendToken.js";
+export * as SwapToken from "./SwapToken.js";
+export * as ViewCast from "./ViewCast.js";
+export * as ViewProfile from "./ViewProfile.js";
+export * as ViewToken from "./ViewToken.js";

package/esm/back.d.ts

@@ -0,0 +1,13 @@
+export type BackState = {
+    /**
+     * Is the back control visible. Note that on mobile devices Farcaster clients
+     * may support a gesture based control rather than button control.
+     *
+     * @default false
+     */
+    visible: boolean;
+};
+export declare const DEFAULT_BACK_STATE: {
+    visible: false;
+};
+export type UpdateBackState = (state: BackState) => Promise<void>;

package/esm/back.js

@@ -0,0 +1,3 @@
+export const DEFAULT_BACK_STATE = {
+    visible: false,
+};

package/esm/context.d.ts

@@ -0,0 +1,94 @@
+import type { MiniAppNotificationDetails } from './schemas/index.ts';
+export type MiniAppUser = {
+    fid: number;
+    username?: string;
+    displayName?: string;
+    pfpUrl?: string;
+};
+export interface MiniAppCast {
+    author: MiniAppUser;
+    hash: string;
+    parentHash?: string;
+    parentFid?: number;
+    timestamp?: number;
+    mentions?: MiniAppUser[];
+    text: string;
+    embeds?: string[];
+    channelKey?: string;
+}
+export type CastEmbedLocationContext = {
+    type: 'cast_embed';
+    embed: string;
+    cast: MiniAppCast;
+};
+export type CastShareLocationContext = {
+    type: 'cast_share';
+    cast: MiniAppCast;
+};
+export type NotificationLocationContext = {
+    type: 'notification';
+    notification: {
+        notificationId: string;
+        title: string;
+        body: string;
+    };
+};
+export type LauncherLocationContext = {
+    type: 'launcher';
+};
+export type ChannelLocationContext = {
+    type: 'channel';
+    channel: {
+        /**
+         * Channel key identifier
+         */
+        key: string;
+        /**
+         * Channel name
+         */
+        name: string;
+        /**
+         * Channel profile image URL
+         */
+        imageUrl?: string;
+    };
+};
+export type LocationContext = CastEmbedLocationContext | CastShareLocationContext | NotificationLocationContext | LauncherLocationContext | ChannelLocationContext;
+export type AccountLocation = {
+    placeId: string;
+    /**
+     * Human-readable string describing the location
+     */
+    description: string;
+};
+export type UserContext = {
+    fid: number;
+    username?: string;
+    displayName?: string;
+    /**
+     * Profile image URL
+     */
+    pfpUrl?: string;
+    location?: AccountLocation;
+};
+export type SafeAreaInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+export type ClientContext = {
+    clientFid: number;
+    added: boolean;
+    notificationDetails?: MiniAppNotificationDetails;
+    safeAreaInsets?: SafeAreaInsets;
+};
+export type ClientFeatures = {
+    haptics: boolean;
+};
+export type MiniAppContext = {
+    client: ClientContext;
+    user: UserContext;
+    location?: LocationContext;
+    features?: ClientFeatures;
+};

package/esm/context.js

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

package/esm/errors.d.ts

@@ -0,0 +1,13 @@
+export type GlobalErrorType<name extends string = 'Error'> = Error & {
+    name: name;
+};
+export declare class BaseError<cause extends Error | undefined = undefined> extends Error {
+    name: string;
+    cause: cause;
+    constructor(message: string, options?: BaseError.Options<cause>);
+}
+export declare namespace BaseError {
+    type Options<cause extends Error | undefined = Error | undefined> = {
+        cause?: cause | undefined;
+    };
+}

package/esm/errors.js

@@ -0,0 +1,8 @@
+export class BaseError extends Error {
+    name = 'BaseError';
+    cause;
+    constructor(message, options = {}) {
+        super(message, options.cause ? { cause: options.cause } : undefined);
+        this.cause = options.cause;
+    }
+}

package/esm/index.d.ts

@@ -0,0 +1,10 @@
+export * from './actions/index.ts';
+export * from './wallet/index.ts';
+export * as Back from './back.ts';
+export * as Errors from './errors.ts';
+export * as Context from './context.ts';
+export * as Manifest from './manifest.ts';
+export * from './types.ts';
+export * from './schemas/index.ts';
+export * from './solana.ts';
+export * from './solanaWire.ts';

package/esm/index.js

@@ -0,0 +1,10 @@
+export * from "./actions/index.js";
+export * from "./wallet/index.js";
+export * as Back from "./back.js";
+export * as Errors from "./errors.js";
+export * as Context from "./context.js";
+export * as Manifest from "./manifest.js";
+export * from "./types.js";
+export * from "./schemas/index.js";
+export * from "./solana.js";
+export * from "./solanaWire.js";

package/esm/internal/types.d.ts

@@ -0,0 +1,8 @@
+type Compute<type> = {
+    [key in keyof type]: type[key];
+} & unknown;
+type KeyofUnion<type> = type extends type ? keyof type : never;
+export type OneOf<union extends object, fallback extends object | undefined = undefined, keys extends KeyofUnion<union> = KeyofUnion<union>> = union extends infer item ? Compute<item & {
+    [key in Exclude<keys, keyof item>]?: fallback extends object ? key extends keyof fallback ? fallback[key] : undefined : undefined;
+}> : never;
+export {};

package/esm/internal/types.js

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

package/esm/manifest.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Farcaster manifest for a domain hosted at `/.well-known/farcaster.json`
+ */
+export type Manifest = {
+    accountAssociation: AccountAssociation;
+    miniapp?: MiniAppConfig;
+    frame?: MiniAppConfig;
+};
+/**
+ * Signed domain association linking this miniapp to a Farcaster account
+ *
+ * A DomainAssociation can be generated using the {@link https://farcaster.xyz/~/developers/domains | Warpcast
+ * Domains Developer} tool.
+ */
+export type AccountAssociation = {
+    /**
+     * Base64URL encoded JFS signature
+     */
+    header: string;
+    /**
+     * Base64URL encoded payload signature
+     */
+    payload: string;
+    /**
+     * Base64URL encoded signature
+     */
+    signature: string;
+};
+/**
+ * MiniApp configuration
+ *
+ * @example
+ * ``ts
+ * const miniapp: MiniAppConfig = {
+ *   version: '1',
+ *   name: 'Yoink!',
+ *   homeUrl: 'https://yoink.party',
+ *   iconUrl: 'https://yoink.party/img/icon.png',
+ *   imageUrl: 'https://yoink.party/framesV2/opengraph-image',
+ *   buttonTitle: '🚩 Start',
+ *   splashImageUrl: 'https://yoink.party/img/splash.png',
+ *   splashImageBackgroundColor: '#eeeee4',
+ *   webhookUrl: 'https://yoink.party/webhook'
+ * };
+ * ``
+ */
+export type MiniAppConfig = {
+    /**
+     * Manifest version
+     *
+     * Must be the literal '1'.
+     */
+    version: '1';
+    /**
+     * App name that will be displayed to users
+     *
+     * Max length of 32 characters.
+     */
+    name: string;
+    /**
+     * Default launch URL
+     *
+     * Max length of 1024 characters.
+     */
+    homeUrl: string;
+    /**
+     * Icon URL
+     *
+     * Max length of 1024 characters. Image must be 200x200px and less than 1MB.
+     */
+    iconUrl: string;
+    /**
+     * Image URL
+     *
+     * Max length of 1024 characters. Image must have a 3:2 ratio.
+     */
+    imageUrl: string;
+    /**
+     * Default button title to use when miniapp is rendered.
+     *
+     * Max length of 32 characters.
+     */
+    buttonTitle: string;
+    /**
+     * Splash image URL
+     *
+     * Max length of 1024 characters. Image must be 200x200px and less than 1MB.
+     */
+    splashImageUrl?: string;
+    /**
+     * Splash background color
+     *
+     * Must be a hex color code.
+     */
+    splashBackgroundColor?: string;
+    /**
+     * URL to which clients will POST server events.
+     * Max length of 1024 characters.
+     * Required if the miniapp application uses notifications.
+     */
+    webhookUrl?: string;
+    /**
+     * Canonical domain for the miniapp application.
+     * If specified, this domain will be treated as the primary domain for the miniapp.
+     * Max length of 1024 characters.
+     */
+    canonicalDomain?: string;
+};
+/**
+ * Helper function to get the MiniApp config from a manifest,
+ * supporting both 'miniapp' and 'frame' properties during the transition period
+ */
+export declare function getMiniAppConfig(manifest: Manifest): MiniAppConfig | undefined;

package/esm/manifest.js

@@ -0,0 +1,7 @@
+/**
+ * Helper function to get the MiniApp config from a manifest,
+ * supporting both 'miniapp' and 'frame' properties during the transition period
+ */
+export function getMiniAppConfig(manifest) {
+    return manifest.miniapp || manifest.frame;
+}

package/esm/schemas/embeds.d.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod/v4';
+export declare const actionLaunchFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"launch_frame">;
+    name: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    splashImageUrl: z.ZodOptional<z.ZodString>;
+    splashBackgroundColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const actionLaunchMiniAppSchema: z.ZodObject<{
+    type: z.ZodLiteral<"launch_miniapp">;
+    name: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    splashImageUrl: z.ZodOptional<z.ZodString>;
+    splashBackgroundColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const actionViewTokenSchema: z.ZodObject<{
+    type: z.ZodLiteral<"view_token">;
+    token: z.ZodString;
+}, z.core.$strip>;
+export declare const actionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"launch_miniapp">;
+    name: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    splashImageUrl: z.ZodOptional<z.ZodString>;
+    splashBackgroundColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"view_token">;
+    token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"launch_frame">;
+    name: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    splashImageUrl: z.ZodOptional<z.ZodString>;
+    splashBackgroundColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export declare const buttonSchema: z.ZodObject<{
+    title: z.ZodString;
+    action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"launch_miniapp">;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        splashImageUrl: z.ZodOptional<z.ZodString>;
+        splashBackgroundColor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"view_token">;
+        token: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"launch_frame">;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        splashImageUrl: z.ZodOptional<z.ZodString>;
+        splashBackgroundColor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+export declare const miniAppEmbedNextSchema: z.ZodObject<{
+    version: z.ZodLiteral<"next">;
+    imageUrl: z.ZodString;
+    aspectRatio: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"1:1">, z.ZodLiteral<"3:2">]>>;
+    button: z.ZodObject<{
+        title: z.ZodString;
+        action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"launch_miniapp">;
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+            splashImageUrl: z.ZodOptional<z.ZodString>;
+            splashBackgroundColor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"view_token">;
+            token: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"launch_frame">;
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+            splashImageUrl: z.ZodOptional<z.ZodString>;
+            splashBackgroundColor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const safeParseMiniAppEmbed: (rawResponse: unknown) => z.ZodSafeParseResult<{
+    version: "next";
+    imageUrl: string;
+    button: {
+        title: string;
+        action: {
+            type: "launch_miniapp";
+            name: string;
+            url?: string | undefined;
+            splashImageUrl?: string | undefined;
+            splashBackgroundColor?: string | undefined;
+        } | {
+            type: "view_token";
+            token: string;
+        } | {
+            type: "launch_frame";
+            name: string;
+            url?: string | undefined;
+            splashImageUrl?: string | undefined;
+            splashBackgroundColor?: string | undefined;
+        };
+    };
+    aspectRatio?: "1:1" | "3:2" | undefined;
+}>;
+export declare const safeParseFrameEmbed: (rawResponse: unknown) => z.ZodSafeParseResult<{
+    version: "next";
+    imageUrl: string;
+    button: {
+        title: string;
+        action: {
+            type: "launch_miniapp";
+            name: string;
+            url?: string | undefined;
+            splashImageUrl?: string | undefined;
+            splashBackgroundColor?: string | undefined;
+        } | {
+            type: "view_token";
+            token: string;
+        } | {
+            type: "launch_frame";
+            name: string;
+            url?: string | undefined;
+            splashImageUrl?: string | undefined;
+            splashBackgroundColor?: string | undefined;
+        };
+    };
+    aspectRatio?: "1:1" | "3:2" | undefined;
+}>;
+export type MiniAppEmbedNext = z.infer<typeof miniAppEmbedNextSchema>;
+export type FrameEmbedNext = MiniAppEmbedNext;

package/esm/schemas/embeds.js

@@ -0,0 +1,39 @@
+import { z } from 'zod/v4';
+import { aspectRatioSchema, buttonTitleSchema, caip19TokenSchema, hexColorSchema, miniAppNameSchema, secureUrlSchema, } from "./shared.js";
+export const actionLaunchFrameSchema = z.object({
+    type: z.literal('launch_frame'),
+    name: miniAppNameSchema,
+    url: secureUrlSchema.optional(),
+    splashImageUrl: secureUrlSchema.optional(),
+    splashBackgroundColor: hexColorSchema.optional(),
+});
+export const actionLaunchMiniAppSchema = z.object({
+    type: z.literal('launch_miniapp'),
+    name: miniAppNameSchema,
+    url: secureUrlSchema.optional(),
+    splashImageUrl: secureUrlSchema.optional(),
+    splashBackgroundColor: hexColorSchema.optional(),
+});
+export const actionViewTokenSchema = z.object({
+    type: z.literal('view_token'),
+    token: caip19TokenSchema,
+});
+export const actionSchema = z.discriminatedUnion('type', [
+    actionLaunchMiniAppSchema,
+    actionViewTokenSchema,
+    // Remove after compatibility period
+    actionLaunchFrameSchema,
+]);
+export const buttonSchema = z.object({
+    title: buttonTitleSchema,
+    action: actionSchema,
+});
+export const miniAppEmbedNextSchema = z.object({
+    version: z.literal('next'),
+    imageUrl: secureUrlSchema,
+    aspectRatio: aspectRatioSchema.optional(),
+    button: buttonSchema,
+});
+export const safeParseMiniAppEmbed = (rawResponse) => miniAppEmbedNextSchema.safeParse(rawResponse);
+// Backward compatibility - also parse fc:frame meta tags
+export const safeParseFrameEmbed = safeParseMiniAppEmbed;

package/esm/schemas/events.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod/v4';
+export declare const eventMiniAppAddedSchema: z.ZodObject<{
+    event: z.ZodLiteral<"miniapp_added">;
+    notificationDetails: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EventMiniAppAdded = z.infer<typeof eventMiniAppAddedSchema>;
+export declare const eventFrameAddedSchema: z.ZodObject<{
+    event: z.ZodLiteral<"frame_added">;
+    notificationDetails: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EventFrameAdded = z.infer<typeof eventFrameAddedSchema>;
+export declare const eventMiniAppRemovedSchema: z.ZodObject<{
+    event: z.ZodLiteral<"miniapp_removed">;
+}, z.core.$strip>;
+export type EventMiniAppRemoved = z.infer<typeof eventMiniAppRemovedSchema>;
+export declare const eventFrameRemovedSchema: z.ZodObject<{
+    event: z.ZodLiteral<"frame_removed">;
+}, z.core.$strip>;
+export type EventFrameRemoved = z.infer<typeof eventFrameRemovedSchema>;
+export declare const eventNotificationsEnabledSchema: z.ZodObject<{
+    event: z.ZodLiteral<"notifications_enabled">;
+    notificationDetails: z.ZodObject<{
+        url: z.ZodNonOptional<z.ZodString>;
+        token: z.ZodNonOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EventNotificationsEnabled = z.infer<typeof eventNotificationsEnabledSchema>;
+export declare const notificationsDisabledSchema: z.ZodObject<{
+    event: z.ZodLiteral<"notifications_disabled">;
+}, z.core.$strip>;
+export type EventNotificationsDisabled = z.infer<typeof notificationsDisabledSchema>;
+export declare const serverEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event: z.ZodLiteral<"miniapp_added">;
+    notificationDetails: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"miniapp_removed">;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"notifications_enabled">;
+    notificationDetails: z.ZodObject<{
+        url: z.ZodNonOptional<z.ZodString>;
+        token: z.ZodNonOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"notifications_disabled">;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"frame_added">;
+    notificationDetails: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"frame_removed">;
+}, z.core.$strip>]>;
+export type MiniAppServerEvent = z.infer<typeof serverEventSchema>;

package/esm/schemas/events.js

@@ -0,0 +1,32 @@
+import { z } from 'zod/v4';
+import { notificationDetailsSchema } from "./notifications.js";
+export const eventMiniAppAddedSchema = z.object({
+    event: z.literal('miniapp_added'),
+    notificationDetails: notificationDetailsSchema.optional(),
+});
+export const eventFrameAddedSchema = z.object({
+    event: z.literal('frame_added'),
+    notificationDetails: notificationDetailsSchema.optional(),
+});
+export const eventMiniAppRemovedSchema = z.object({
+    event: z.literal('miniapp_removed'),
+});
+export const eventFrameRemovedSchema = z.object({
+    event: z.literal('frame_removed'),
+});
+export const eventNotificationsEnabledSchema = z.object({
+    event: z.literal('notifications_enabled'),
+    notificationDetails: notificationDetailsSchema.required(),
+});
+export const notificationsDisabledSchema = z.object({
+    event: z.literal('notifications_disabled'),
+});
+export const serverEventSchema = z.discriminatedUnion('event', [
+    eventMiniAppAddedSchema,
+    eventMiniAppRemovedSchema,
+    eventNotificationsEnabledSchema,
+    notificationsDisabledSchema,
+    // Remove after compatibility period
+    eventFrameAddedSchema,
+    eventFrameRemovedSchema,
+]);

package/esm/schemas/index.d.ts

@@ -0,0 +1,5 @@
+export * from './embeds.ts';
+export * from './events.ts';
+export * from './shared.ts';
+export * from './manifest.ts';
+export * from './notifications.ts';

package/esm/schemas/index.js

@@ -0,0 +1,5 @@
+export * from "./embeds.js";
+export * from "./events.js";
+export * from "./shared.js";
+export * from "./manifest.js";
+export * from "./notifications.js";