@pepu-chain/sdk 0.0.0-stage → 0.2.0

package/dist/session/kernel.d.ts

@@ -0,0 +1,131 @@
+import { Policy } from '@zerodev/permissions';
+import { Address, PublicClient, Hex } from 'viem';
+import { KernelOwner, KernelSmartAccount } from '../aa/kernel.js';
+export { KERNEL_VERSION, getKernelAddress } from '../aa/kernel.js';
+import { K as KernelSessionCall } from '../scope-DBRkN7bR.js';
+export { A as ApprovalCheck, a as KernelSessionScope, P as ParsedApproval, c as checkApproval, d as describeKernelSessionScope, i as isCallInScope, p as parseApproval } from '../scope-DBRkN7bR.js';
+export { a as SessionRecord, S as SessionStore, c as createMemoryStore, i as isLive } from '../store-CjmLgp9g.js';
+import '@zerodev/sdk/types';
+import '@zerodev/sdk';
+import '../erc7677-DOW58QBE.js';
+import '../types-BilBTDqK.js';
+import '../calls-z_EQOtFb.js';
+
+/**
+ * `@pepu-chain/sdk/session/kernel`: on-chain session keys with ZeroDev Kernel
+ * permissions. Extracted from templates/sponsored-session-app/lib/{kernel,
+ * session-policy,approval}.ts and built on `toPepuKernelAccount`
+ * (`plugins.regular`).
+ *
+ * The scope is enforced ON-CHAIN by ZeroDev's policy contracts, which the
+ * user's Kernel account calls during UserOperation validation:
+ *
+ * - Call policy v0.0.4: only the listed targets and function selectors, with a
+ *   native value no larger than `valueLimit` (default 0).
+ * - Timestamp policy: the permission is invalid outside `validAfter`..`validUntil`.
+ *
+ * A UserOperation outside this scope is rejected by the EntryPoint itself, no
+ * matter who relays it or what the app backend does.
+ *
+ * Deployed on PEPU mainnet (eth_getCode verified 2026-10-02): Kernel v3.1
+ * factory 0xaac5D4240AF87249B3f71BC8E4A2cae074A3E419, ECDSA validator
+ * 0x845ADb2C711129d4f3966735eD98a9F09fC4cE57, ECDSA signer module
+ * 0x6A6F069E2a08c2468e7724Ab3250CdBFBA14D4FF, call policy v0.0.4 and the
+ * timestamp policy below. Call policy v0.0.5 is NOT deployed on PEPU, so the
+ * version is pinned.
+ *
+ * Optional peers: `@zerodev/sdk`, `@zerodev/permissions`, `@zerodev/ecdsa-validator`.
+ */
+/** Call policy v0.0.4. Pinned: v0.0.5 is not deployed on PEPU mainnet. */
+declare const CALL_POLICY_V0_0_4_ADDRESS: Address;
+/** ZeroDev timestamp policy on PEPU mainnet. */
+declare const TIMESTAMP_POLICY_ADDRESS: Address;
+/**
+ * Worst-case gas the paymaster policy service RESERVES per sponsored operation,
+ * measured on PEPU mainnet with the sponsored-session-app template: the first
+ * operation of a session (account deploy plus enabling the permission) about
+ * 20.5 PEPU, later operations about 6.9 PEPU. The real first-session cost was
+ * about 12.8 PEPU for two operations. Size per-user hourly and daily spend
+ * caps above these, or users hit `trailing-hour spend ... would exceed cap`
+ * after their first action.
+ */
+declare const SESSION_GAS_RESERVATION_PEPU: {
+    readonly firstOperation: 20.5;
+    readonly laterOperation: 6.9;
+};
+/**
+ * The on-chain policies for one session: call policy v0.0.4 plus the timestamp
+ * policy. Pure and deterministic given its input. Only the named function
+ * fragments go into the policy, which keeps the grant small.
+ *
+ * @example
+ * const policies = buildKernelSessionPolicies({
+ *   calls: [{ target: tapScore, abi: tapScoreAbi, functionName: "tap" }],
+ *   validUntil: Math.floor(Date.now() / 1000) + 900,
+ * });
+ */
+declare function buildKernelSessionPolicies(p: {
+    calls: readonly KernelSessionCall[];
+    validUntil: number;
+    validAfter?: number;
+}): Policy[];
+/**
+ * A fresh random session key. SERVER ONLY: the private key must never reach
+ * the browser. Only the address is sent to the owner for approval.
+ *
+ * @example
+ * const { privateKey, address } = generateSessionKey();
+ */
+declare function generateSessionKey(): {
+    privateKey: Hex;
+    address: Address;
+};
+/**
+ * The permission id the chain derives for this session key plus these
+ * policies. The server compares it with a browser-supplied approval.
+ *
+ * @example
+ * const permissionId = await expectedPermissionId({ publicClient, sessionKeyAddress, policies });
+ */
+declare function expectedPermissionId(p: {
+    publicClient: PublicClient;
+    sessionKeyAddress: Address;
+    policies: Policy[];
+}): Promise<string>;
+/**
+ * In the user's browser: the owner (the Privy embedded wallet, the only thing
+ * that can authorize a session) signs ONE EIP-712 message that enables a
+ * permission validator on their Kernel account. That signature is the whole
+ * grant. It names the session key's public address (never its private key)
+ * and the policies. The returned `approval` holds no secret: it is the enable
+ * signature plus the policy parameters, useless without the session key.
+ *
+ * @example
+ * const { approval, kernelAddress } = await approveKernelSession({
+ *   publicClient, owner: walletClient, sessionKeyAddress, policies,
+ * });
+ */
+declare function approveKernelSession(p: {
+    publicClient: PublicClient;
+    owner: KernelOwner;
+    sessionKeyAddress: Address;
+    policies: Policy[];
+}): Promise<{
+    approval: string;
+    kernelAddress: Address;
+}>;
+/**
+ * On the server: rebuild the session's Kernel account from the approval and
+ * the server-held session key (an ECDSA signer for that key). No owner
+ * signature is involved. Pass the result to `createPepuSponsoredClient`.
+ *
+ * @example
+ * const account = await loadKernelSessionAccount({ publicClient, approval, sessionPrivateKey });
+ */
+declare function loadKernelSessionAccount(p: {
+    publicClient: PublicClient;
+    approval: string;
+    sessionPrivateKey: Hex;
+}): Promise<KernelSmartAccount>;
+
+export { CALL_POLICY_V0_0_4_ADDRESS, KernelOwner, KernelSessionCall, KernelSmartAccount, SESSION_GAS_RESERVATION_PEPU, TIMESTAMP_POLICY_ADDRESS, approveKernelSession, buildKernelSessionPolicies, expectedPermissionId, generateSessionKey, loadKernelSessionAccount };

package/dist/session/kernel.js

@@ -0,0 +1,13 @@
+export { CALL_POLICY_V0_0_4_ADDRESS, SESSION_GAS_RESERVATION_PEPU, TIMESTAMP_POLICY_ADDRESS, approveKernelSession, buildKernelSessionPolicies, createMemoryStore, expectedPermissionId, generateSessionKey, isLive, loadKernelSessionAccount } from '../chunk-KVG3AYYR.js';
+export { KERNEL_VERSION, getKernelAddress } from '../chunk-ZB6SVBK4.js';
+import '../chunk-IB2FSPMJ.js';
+import '../chunk-VBH3JLQ5.js';
+import '../chunk-IY3ALPUJ.js';
+import '../chunk-D52PADVY.js';
+export { checkApproval, describeKernelSessionScope, isCallInScope, parseApproval } from '../chunk-ESMNAXUI.js';
+import '../chunk-J6UXXHBE.js';
+import '../chunk-XC4IBCI2.js';
+import '../chunk-VTQIHMF3.js';
+import '../chunk-6DSZ4Z2N.js';
+//# sourceMappingURL=kernel.js.map
+//# sourceMappingURL=kernel.js.map

package/dist/session/kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"kernel.js"}

package/dist/session/react.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+var chunkR5PXQNO3_cjs = require('../chunk-R5PXQNO3.cjs');
+require('../chunk-DH6BFNVJ.cjs');
+require('../chunk-NE3QKDOB.cjs');
+require('../chunk-DPCZJLB3.cjs');
+require('../chunk-C2XW44FI.cjs');
+require('../chunk-YQL7NISX.cjs');
+
+
+
+Object.defineProperty(exports, "deriveSessionState", {
+  enumerable: true,
+  get: function () { return chunkR5PXQNO3_cjs.deriveSessionState; }
+});
+Object.defineProperty(exports, "errorFromResponse", {
+  enumerable: true,
+  get: function () { return chunkR5PXQNO3_cjs.errorFromResponse; }
+});
+Object.defineProperty(exports, "useSessionAct", {
+  enumerable: true,
+  get: function () { return chunkR5PXQNO3_cjs.useSessionAct; }
+});
+Object.defineProperty(exports, "useSessionGrant", {
+  enumerable: true,
+  get: function () { return chunkR5PXQNO3_cjs.useSessionGrant; }
+});
+Object.defineProperty(exports, "useSessionRevoke", {
+  enumerable: true,
+  get: function () { return chunkR5PXQNO3_cjs.useSessionRevoke; }
+});
+Object.defineProperty(exports, "useSessionStatus", {
+  enumerable: true,
+  get: function () { return chunkR5PXQNO3_cjs.useSessionStatus; }
+});
+//# sourceMappingURL=react.cjs.map
+//# sourceMappingURL=react.cjs.map

package/dist/session/react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"react.cjs"}

package/dist/session/react.d.cts

@@ -0,0 +1,119 @@
+import { P as PepuError } from '../errors-CgX1vNj7.cjs';
+import 'viem';
+
+/**
+ * Client hooks for the Privy-mode session. Ported from
+ * templates/game-app/components/session-consent-screen.tsx and
+ * session-status-card.tsx. Auth defaults to `usePepuAuthFetch` from
+ * `@pepu-chain/sdk/privy/react` (Privy bearer token); pass `authFetch` to use
+ * your own.
+ */
+/** A fetch that adds the user's Privy bearer token. */
+type AuthFetch = (url: string, init?: RequestInit) => Promise<Response>;
+interface BaseOptions {
+    /** Custom authenticated fetch. Default: `usePepuAuthFetch()` (Privy bearer token). */
+    authFetch?: AuthFetch;
+    /** The embedded wallet address. Default: the Privy user's wallet. */
+    address?: string;
+}
+/**
+ * Turn a non-OK route response into a typed error. Reads the
+ * `{ error: { code, message, hint } }` body the SDK route factories return.
+ * Only a 409 means "no session" (`SESSION_NONE`).
+ *
+ * @example
+ * if (!res.ok) throw await errorFromResponse(res);
+ */
+declare function errorFromResponse(res: Response): Promise<PepuError>;
+/** Session state from the server's `delegated` flag and the locally tracked expiry. */
+type SessionState = "none" | "active" | "expired";
+/**
+ * Derive the session state. A delegated signer with a known expiry in the
+ * past is `expired` (Privy denies it, but the signer still exists until
+ * revoked). Pure.
+ *
+ * @example
+ * deriveSessionState({ delegated: true, expiresAt: 100, nowSeconds: 200 }); // { state: "expired", secondsLeft: 0 }
+ */
+declare function deriveSessionState(p: {
+    delegated: boolean;
+    expiresAt?: number | undefined;
+    nowSeconds: number;
+}): {
+    state: SessionState;
+    secondsLeft?: number;
+};
+type SessionGrantStatus = "idle" | "creating-policy" | "awaiting-consent" | "granted" | "error";
+/**
+ * Grant a session: POST the grant route, then ask the user to approve with
+ * Privy's `addSigners`. Skips `addSigners` when the server says
+ * `alreadyGranted`, and swallows Privy's "duplicate signer" error.
+ *
+ * @example
+ * const { grant, status, error } = useSessionGrant();
+ * <button onClick={grant} disabled={status === "creating-policy"}>Grant</button>
+ */
+declare function useSessionGrant(o?: BaseOptions & {
+    grantEndpoint?: string;
+}): {
+    grant(): Promise<void>;
+    status: SessionGrantStatus;
+    error?: PepuError;
+};
+/**
+ * Current session state. Asks the status route whether a signer is attached
+ * and combines it with the expiry tracked from the grant. Ticks every second
+ * for `secondsLeft`; re-polls every `pollMs` if given.
+ *
+ * @example
+ * const { state, secondsLeft } = useSessionStatus({ pollMs: 30_000 });
+ */
+declare function useSessionStatus(o?: BaseOptions & {
+    statusEndpoint?: string;
+    pollMs?: number;
+}): {
+    state: SessionState;
+    /**
+     * True until the first status response (or failure) has been applied. Show a
+     * spinner while it is true so the "start a session" UI does not flash on reload.
+     */
+    loading: boolean;
+    expiresAt?: number;
+    secondsLeft?: number;
+    refetch(): void;
+};
+type SessionRevokeStatus = "idle" | "revoking" | "revoked" | "error";
+/**
+ * Revoke the session. The Privy `removeSigners` call is the real revoke; the
+ * server revoke route afterwards is best-effort cleanup of the policy.
+ *
+ * @example
+ * const { revoke, status } = useSessionRevoke();
+ */
+declare function useSessionRevoke(o?: BaseOptions & {
+    revokeEndpoint?: string;
+}): {
+    revoke(): Promise<void>;
+    status: SessionRevokeStatus;
+    error?: PepuError;
+};
+type SessionActStatus = "idle" | "pending" | "success" | "error";
+/**
+ * Call a session action route (built with `createSessionActionRoute`). A 409
+ * is the only "no session" signal and surfaces as `error.code ===
+ * "SESSION_NONE"`; any other failure is a failed transaction, so do not send
+ * the user back to the consent screen for it.
+ *
+ * @example
+ * const { act } = useSessionAct<{}, { hash: string }>({ endpoint: "/api/game/tap" });
+ * const { hash } = await act({});
+ */
+declare function useSessionAct<I, O>(o: BaseOptions & {
+    endpoint: string;
+}): {
+    act(input: I): Promise<O>;
+    status: SessionActStatus;
+    error?: PepuError;
+};
+
+export { type AuthFetch, type SessionActStatus, type SessionGrantStatus, type SessionRevokeStatus, type SessionState, deriveSessionState, errorFromResponse, useSessionAct, useSessionGrant, useSessionRevoke, useSessionStatus };

package/dist/session/react.d.ts

@@ -0,0 +1,119 @@
+import { P as PepuError } from '../errors-CgX1vNj7.js';
+import 'viem';
+
+/**
+ * Client hooks for the Privy-mode session. Ported from
+ * templates/game-app/components/session-consent-screen.tsx and
+ * session-status-card.tsx. Auth defaults to `usePepuAuthFetch` from
+ * `@pepu-chain/sdk/privy/react` (Privy bearer token); pass `authFetch` to use
+ * your own.
+ */
+/** A fetch that adds the user's Privy bearer token. */
+type AuthFetch = (url: string, init?: RequestInit) => Promise<Response>;
+interface BaseOptions {
+    /** Custom authenticated fetch. Default: `usePepuAuthFetch()` (Privy bearer token). */
+    authFetch?: AuthFetch;
+    /** The embedded wallet address. Default: the Privy user's wallet. */
+    address?: string;
+}
+/**
+ * Turn a non-OK route response into a typed error. Reads the
+ * `{ error: { code, message, hint } }` body the SDK route factories return.
+ * Only a 409 means "no session" (`SESSION_NONE`).
+ *
+ * @example
+ * if (!res.ok) throw await errorFromResponse(res);
+ */
+declare function errorFromResponse(res: Response): Promise<PepuError>;
+/** Session state from the server's `delegated` flag and the locally tracked expiry. */
+type SessionState = "none" | "active" | "expired";
+/**
+ * Derive the session state. A delegated signer with a known expiry in the
+ * past is `expired` (Privy denies it, but the signer still exists until
+ * revoked). Pure.
+ *
+ * @example
+ * deriveSessionState({ delegated: true, expiresAt: 100, nowSeconds: 200 }); // { state: "expired", secondsLeft: 0 }
+ */
+declare function deriveSessionState(p: {
+    delegated: boolean;
+    expiresAt?: number | undefined;
+    nowSeconds: number;
+}): {
+    state: SessionState;
+    secondsLeft?: number;
+};
+type SessionGrantStatus = "idle" | "creating-policy" | "awaiting-consent" | "granted" | "error";
+/**
+ * Grant a session: POST the grant route, then ask the user to approve with
+ * Privy's `addSigners`. Skips `addSigners` when the server says
+ * `alreadyGranted`, and swallows Privy's "duplicate signer" error.
+ *
+ * @example
+ * const { grant, status, error } = useSessionGrant();
+ * <button onClick={grant} disabled={status === "creating-policy"}>Grant</button>
+ */
+declare function useSessionGrant(o?: BaseOptions & {
+    grantEndpoint?: string;
+}): {
+    grant(): Promise<void>;
+    status: SessionGrantStatus;
+    error?: PepuError;
+};
+/**
+ * Current session state. Asks the status route whether a signer is attached
+ * and combines it with the expiry tracked from the grant. Ticks every second
+ * for `secondsLeft`; re-polls every `pollMs` if given.
+ *
+ * @example
+ * const { state, secondsLeft } = useSessionStatus({ pollMs: 30_000 });
+ */
+declare function useSessionStatus(o?: BaseOptions & {
+    statusEndpoint?: string;
+    pollMs?: number;
+}): {
+    state: SessionState;
+    /**
+     * True until the first status response (or failure) has been applied. Show a
+     * spinner while it is true so the "start a session" UI does not flash on reload.
+     */
+    loading: boolean;
+    expiresAt?: number;
+    secondsLeft?: number;
+    refetch(): void;
+};
+type SessionRevokeStatus = "idle" | "revoking" | "revoked" | "error";
+/**
+ * Revoke the session. The Privy `removeSigners` call is the real revoke; the
+ * server revoke route afterwards is best-effort cleanup of the policy.
+ *
+ * @example
+ * const { revoke, status } = useSessionRevoke();
+ */
+declare function useSessionRevoke(o?: BaseOptions & {
+    revokeEndpoint?: string;
+}): {
+    revoke(): Promise<void>;
+    status: SessionRevokeStatus;
+    error?: PepuError;
+};
+type SessionActStatus = "idle" | "pending" | "success" | "error";
+/**
+ * Call a session action route (built with `createSessionActionRoute`). A 409
+ * is the only "no session" signal and surfaces as `error.code ===
+ * "SESSION_NONE"`; any other failure is a failed transaction, so do not send
+ * the user back to the consent screen for it.
+ *
+ * @example
+ * const { act } = useSessionAct<{}, { hash: string }>({ endpoint: "/api/game/tap" });
+ * const { hash } = await act({});
+ */
+declare function useSessionAct<I, O>(o: BaseOptions & {
+    endpoint: string;
+}): {
+    act(input: I): Promise<O>;
+    status: SessionActStatus;
+    error?: PepuError;
+};
+
+export { type AuthFetch, type SessionActStatus, type SessionGrantStatus, type SessionRevokeStatus, type SessionState, deriveSessionState, errorFromResponse, useSessionAct, useSessionGrant, useSessionRevoke, useSessionStatus };

package/dist/session/react.js

@@ -0,0 +1,8 @@
+export { deriveSessionState, errorFromResponse, useSessionAct, useSessionGrant, useSessionRevoke, useSessionStatus } from '../chunk-T43PQXJD.js';
+import '../chunk-EHBPIYY4.js';
+import '../chunk-JLZ4LZ4Z.js';
+import '../chunk-VTQIHMF3.js';
+import '../chunk-3XUGQODR.js';
+import '../chunk-6DSZ4Z2N.js';
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/session/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"react.js"}