@farcaster/frame-core 0.0.0-canary-20250430150627

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Merkle Manufactory Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @farcaster/frame-core
+
+Build onchain social apps
+
+## Installation
+
+```bash
+pnpm add @farcaster/core
+```
+
+## Documentation
+
+For documentation and guides, visit [miniapps.farcaster.xyz](https://miniapps.farcaster.xyz).

package/dist/actions/AddFrame.d.ts

@@ -0,0 +1,36 @@
+import * as Errors from '../errors';
+import type { OneOf } from '../internal/types';
+import type { FrameNotificationDetails } from '../schemas';
+export type AddFrameResult = {
+    notificationDetails?: FrameNotificationDetails;
+};
+export type AddFrame = () => Promise<AddFrameResult>;
+type InvalidDomainManifestJsonError = {
+    type: 'invalid_domain_manifest';
+};
+type RejectedByUserJsonError = {
+    type: 'rejected_by_user';
+};
+export type AddFrameJsonError = InvalidDomainManifestJsonError | RejectedByUserJsonError;
+export type AddFrameRejectedReason = AddFrameJsonError['type'];
+export type AddFrameJsonResult = OneOf<{
+    result: AddFrameResult;
+} | {
+    error: AddFrameJsonError;
+}>;
+export type WireAddFrame = () => Promise<AddFrameJsonResult>;
+/**
+ * Thrown when the frame does not have a valid domain manifest.
+ */
+export declare class InvalidDomainManifest extends Errors.BaseError {
+    readonly name = "AddFrame.InvalidDomainManifest";
+    constructor();
+}
+/**
+ * Thrown when add frame action was rejected by the user.
+ */
+export declare class RejectedByUser extends Errors.BaseError {
+    readonly name = "AddFrame.RejectedByUser";
+    constructor();
+}
+export {};

package/dist/actions/AddFrame.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RejectedByUser = exports.InvalidDomainManifest = void 0;
+const Errors = __importStar(require("../errors"));
+/**
+ * Thrown when the frame does not have a valid domain manifest.
+ */
+class InvalidDomainManifest extends Errors.BaseError {
+    name = 'AddFrame.InvalidDomainManifest';
+    constructor() {
+        super('Invalid domain manifest');
+    }
+}
+exports.InvalidDomainManifest = InvalidDomainManifest;
+/**
+ * Thrown when add frame action was rejected by the user.
+ */
+class RejectedByUser extends Errors.BaseError {
+    name = 'AddFrame.RejectedByUser';
+    constructor() {
+        super('Add frame rejected by user');
+    }
+}
+exports.RejectedByUser = RejectedByUser;

package/dist/actions/ComposeCast.d.ts

@@ -0,0 +1,32 @@
+export type Options<close extends boolean | undefined = undefined> = {
+    /**
+     * Suggested text for the body of the cast.
+     *
+     * Mentions can be included using the human-writeable form (e.g. @farcaster).
+     **/
+    text?: string;
+    /** Suggested embeds. Max two. */
+    embeds?: [] | [string] | [string, string];
+    /** Suggested parent. */
+    parent?: {
+        type: 'cast';
+        hash: string;
+    };
+    /** Whether the app should be closed when this action is called. */
+    close?: close;
+};
+export type Result<close extends boolean | undefined = undefined> = close extends true ? undefined : {
+    cast: {
+        /** Cast of the created cast */
+        hash: string;
+        /** Text of the created cast */
+        text?: string;
+        /** Embeds of the created cast */
+        embeds?: [] | [string] | [string, string];
+        /** Parent of the created cast */
+        parent?: {
+            type: 'cast';
+            hash: string;
+        };
+    };
+};

package/dist/actions/ComposeCast.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/actions/Ready.d.ts

@@ -0,0 +1,13 @@
+export type ReadyOptions = {
+    /**
+     * Disable native gestures. Use this option if your frame uses gestures
+     * that conflict with native gestures.
+     *
+     * @defaultValue false
+     */
+    disableNativeGestures: boolean;
+};
+export declare const DEFAULT_READY_OPTIONS: {
+    disableNativeGestures: false;
+};
+export type Ready = (options?: Partial<ReadyOptions>) => void;

package/dist/actions/Ready.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_READY_OPTIONS = void 0;
+exports.DEFAULT_READY_OPTIONS = {
+    disableNativeGestures: false,
+};

package/dist/actions/SendToken.d.ts

@@ -0,0 +1,48 @@
+export type SendTokenOptions = {
+    /**
+     * CAIP-19 asset ID
+     * For example, Base USDC:
+     * eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+     */
+    token?: string;
+    /**
+     * Token amount, as numeric string.
+     * For example, 10 USDC: 1000000
+     */
+    amount?: string;
+    /**
+     * Recipient address.
+     */
+    recipientAddress?: string;
+    /**
+     * Recipient fid.
+     */
+    recipientFid?: number;
+};
+type SendTokenDetails = {
+    /**
+     * Tx identifier.
+     */
+    transaction: `0x${string}`;
+};
+type SendTokenErrorDetails = {
+    /**
+     * Error code.
+     */
+    error: string;
+    /**
+     * Error message.
+     */
+    message?: string;
+};
+export type SendTokenErrorReason = 'rejected_by_user' | 'send_failed';
+export type SendTokenResult = {
+    success: true;
+    send: SendTokenDetails;
+} | {
+    success: false;
+    reason: SendTokenErrorReason;
+    error?: SendTokenErrorDetails;
+};
+export type SendToken = (options: SendTokenOptions) => Promise<SendTokenResult>;
+export {};

package/dist/actions/SendToken.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/actions/SignIn.d.ts

@@ -0,0 +1,41 @@
+import * as Errors from '../errors';
+import type { OneOf } from '../internal/types';
+export type SignInOptions = {
+    /**
+     * A random string used to prevent replay attacks.
+     */
+    nonce: string;
+    /**
+     * Start time at which the signature becomes valid.
+     * ISO 8601 datetime.
+     */
+    notBefore?: string;
+    /**
+     * Expiration time at which the signature is no longer valid.
+     * ISO 8601 datetime.
+     */
+    expirationTime?: string;
+};
+export type SignInResult = {
+    signature: string;
+    message: string;
+};
+export type SignIn = (options: SignInOptions) => Promise<SignInResult>;
+type RejectedByUserJsonError = {
+    type: 'rejected_by_user';
+};
+export type SignInJsonError = RejectedByUserJsonError;
+export type SignInJsonResult = OneOf<{
+    result: SignInResult;
+} | {
+    error: SignInJsonError;
+}>;
+export type WireSignIn = (options: SignInOptions) => Promise<SignInJsonResult>;
+/**
+ * Thrown when a sign in action was rejected.
+ */
+export declare class RejectedByUser extends Errors.BaseError {
+    readonly name = "SignIn.RejectedByUser";
+    constructor();
+}
+export {};

package/dist/actions/SignIn.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RejectedByUser = void 0;
+const Errors = __importStar(require("../errors"));
+/**
+ * Thrown when a sign in action was rejected.
+ */
+class RejectedByUser extends Errors.BaseError {
+    name = 'SignIn.RejectedByUser';
+    constructor() {
+        super('Sign in rejected by user');
+    }
+}
+exports.RejectedByUser = RejectedByUser;

package/dist/actions/SwapToken.d.ts

@@ -0,0 +1,46 @@
+export type SwapTokenOptions = {
+    /**
+     * CAIP-19 asset ID
+     * For example, Base USDC:
+     * eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+     */
+    sellToken?: string;
+    /**
+     * CAIP-19 token ID. For example, OP ETH:
+     * eip155:10/native
+     */
+    buyToken?: string;
+    /**
+     * Sell token amount, as numeric string.
+     * For example, 10 USDC: 1000000
+     */
+    sellAmount?: string;
+};
+type SwapTokenDetails = {
+    /**
+     * Array of tx identifiers in order of execution.
+     * Some swaps will have both an approval and swap tx.
+     */
+    transactions: `0x${string}`[];
+};
+type SwapTokenErrorDetails = {
+    /**
+     * Error code.
+     */
+    error: string;
+    /**
+     * Error message.
+     */
+    message?: string;
+};
+export type SwapErrorReason = 'rejected_by_user' | 'swap_failed';
+export type SwapTokenResult = {
+    success: true;
+    swap: SwapTokenDetails;
+} | {
+    success: false;
+    reason: SwapErrorReason;
+    error?: SwapTokenErrorDetails;
+};
+export type SwapToken = (options: SwapTokenOptions) => Promise<SwapTokenResult>;
+export {};

package/dist/actions/SwapToken.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/actions/ViewProfile.d.ts

@@ -0,0 +1,4 @@
+export type ViewProfileOptions = {
+    fid: number;
+};
+export type ViewProfile = (options: ViewProfileOptions) => Promise<void>;

package/dist/actions/ViewProfile.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/actions/ViewToken.d.ts

@@ -0,0 +1,4 @@
+export type ViewTokenOptions = {
+    token: string;
+};
+export type ViewToken = (options: ViewTokenOptions) => Promise<void>;

package/dist/actions/ViewToken.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/actions/index.d.ts

@@ -0,0 +1,8 @@
+export * as AddFrame from './AddFrame';
+export * as ComposeCast from './ComposeCast';
+export * as Ready from './Ready';
+export * as SignIn from './SignIn';
+export * as SendToken from './SendToken';
+export * as SwapToken from './SwapToken';
+export * as ViewProfile from './ViewProfile';
+export * as ViewToken from './ViewToken';

package/dist/actions/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewToken = exports.ViewProfile = exports.SwapToken = exports.SendToken = exports.SignIn = exports.Ready = exports.ComposeCast = exports.AddFrame = void 0;
+exports.AddFrame = __importStar(require("./AddFrame"));
+exports.ComposeCast = __importStar(require("./ComposeCast"));
+exports.Ready = __importStar(require("./Ready"));
+exports.SignIn = __importStar(require("./SignIn"));
+exports.SendToken = __importStar(require("./SendToken"));
+exports.SwapToken = __importStar(require("./SwapToken"));
+exports.ViewProfile = __importStar(require("./ViewProfile"));
+exports.ViewToken = __importStar(require("./ViewToken"));

package/dist/context.d.ts

@@ -0,0 +1,72 @@
+import type { FrameNotificationDetails } from './schemas';
+export type CastEmbedLocationContext = {
+    type: 'cast_embed';
+    embed: string;
+    cast: {
+        fid: number;
+        hash: string;
+    };
+};
+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 | 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?: FrameNotificationDetails;
+    safeAreaInsets?: SafeAreaInsets;
+};
+export type FrameContext = {
+    client: ClientContext;
+    user: UserContext;
+    location?: LocationContext;
+};

package/dist/context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/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/dist/errors.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseError = void 0;
+class BaseError extends Error {
+    name = 'BaseError';
+    cause;
+    constructor(message, options = {}) {
+        super(message, options.cause ? { cause: options.cause } : undefined);
+        this.cause = options.cause;
+    }
+}
+exports.BaseError = BaseError;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './actions';
+export * from './wallet';
+export * as Errors from './errors';
+export * as Context from './context';
+export * as Manifest from './manifest';
+export * from './types';
+export * from './schemas';

package/dist/index.js

@@ -0,0 +1,46 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Manifest = exports.Context = exports.Errors = void 0;
+__exportStar(require("./actions"), exports);
+__exportStar(require("./wallet"), exports);
+exports.Errors = __importStar(require("./errors"));
+exports.Context = __importStar(require("./context"));
+exports.Manifest = __importStar(require("./manifest"));
+__exportStar(require("./types"), exports);
+__exportStar(require("./schemas"), exports);

package/dist/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/dist/internal/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });