Feature/use checkout hook by Rodriguespn · Pull Request #102 · alpic-ai/skybridge

Rodriguespn · 2025-12-16T11:41:43Z

Greptile Overview

Greptile Summary

This PR adds Instant Checkout support for ChatGPT apps through a new useCheckout hook, following the ACP specification. The implementation includes comprehensive TypeScript types, thorough test coverage, and good documentation.

Major changes:

New useCheckout hook for payment processing with window.openai.requestCheckout
Refactored useCallTool to use shared useAsyncOperation hook for state management
Added useAsyncOperation hook to extract common async operation patterns with deduplication support
Complete TypeScript type definitions for checkout sessions, responses, and errors
Comprehensive test suites for both new hooks (443 lines for checkout, 411 lines for async operations)
Detailed API documentation with multiple usage examples

Issues found:

Minor state inconsistency risk with sessionId when deduplication is enabled
Unrelated change in widgetsDevServer.ts that removes unused variable destructuring

The refactoring is well-executed, consolidating duplicate state management logic into a reusable hook. The checkout implementation follows existing patterns from useCallTool, providing both callback-based and async/await APIs.

Confidence Score: 4/5

This PR is safe to merge with minor considerations for the identified state management edge case
The implementation is well-designed with comprehensive tests, clear documentation, and follows established patterns in the codebase. The refactoring consolidates duplicate code effectively. The identified sessionId state inconsistency is a minor edge case that would only manifest under rapid sequential checkout calls, which is unlikely in practice. The unrelated widgetsDevServer change is cosmetic and unlikely to cause issues.
The use-checkout.ts file could benefit from addressing the sessionId state management if handling rapid sequential checkouts is a requirement

fredericbarthelet · 2025-12-16T23:10:26Z

Thanks @Rodriguespn for taking on this one. Let me know when you want to have a first review to discuss the API and the implementation ;)

Rodriguespn · 2025-12-17T09:20:45Z

Thanks @Rodriguespn for taking on this one. Let me know when you want to have a first review to discuss the API and the implementation ;)

Hey @fredericbarthelet, I've marked the PR as a review because I didn't have the time to properly test it on chatgpt. The implementation seems to be ready to be tested (it's vibe coded so I would proceed with caution). Will try to find some time between today and tomorrow to test this on chatgpt but if you find the time yourself feel free to test it on your end.

greptile-apps

Additional Comments (1)

src/web/hooks/use-checkout.ts, line 155-163 (link)

logic: double state update when requestCheckout returns an error response - state is set here (lines 157-161) then thrown and caught by the catch block below which sets state again (lines 179-183)

this causes redundant setCheckoutState calls. consider removing the throw on line 162 and just returning early after setting the error state, or remove the state update here and let the catch block handle it

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{5 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

Rodriguespn · 2025-12-19T17:20:59Z

@fredericbarthelet tested and ready to be reviewed. I've also added a examples package with a very simple checkout app using Skybridge and Stripe based on an app made by xmcp. Let me know if you guys want to keep it. Happy to remove it if not 😄

Rodriguespn · 2025-12-31T12:40:26Z

Hey @fredericbarthelet @qchuchu, just checking if this feature still makes sense to be in Skybridge. Happy to steer this in the right direction.

fredericbarthelet · 2025-12-31T13:50:02Z

Hey @Rodriguespn, this feature still makes sense. Sorry for not reviewing this earlier. Adapting for MCP App compatibility took a bit of bandwitdth.

I've red your implementations of useCheckout. Thanks for putting this together! It achieves a great lot and we're looking forward to release this in Skybridge.

I need to ask for a few changes in order to make to move this forward:

the exemple app does not leverage useCheckout hook you just added. It will be difficult to provide an example implementation ATM since only a subset of approved partners have access to the feature. We're fine leaving the example implementation outside the scope of this PR in the meantime
please do not use in file comments as documentation
the codebase of useCheckout contains a lot of duplicated code from useCallTool. Might be worth refactor and consolidate the shared code base.
there are specificities in checkout implementation that diverges from a pure copy of useCallTool. Namely:
- the unique checkout session id generation (the hook can provide one by default and be overridable by hook argument checkoutSessionIdGenerator which by default could be checkoutSessionIdGenerator: () => randomUUID(). You should expose this id in the return payload of the hook as well
- the response that is an order straight away instead of a data attribute
the ACP implementation from OpenAI requires a server tool implementation as well - docs. This tool could be configured and properly typed with an additional superset method of the Server class exposed by skybridge/server. Could you make an implementation proposal in a separate PR at a later stage too :)?

WDYT ?

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Implement Fred's suggestions #2 and alpic-ai#3: **Code Consolidation (#2):** - Create shared useAsyncOperation base hook - Extract common async state management patterns - Refactor useCheckout to use base hook - Refactor useCallTool to use base hook with deduplication - Eliminate ~80-100 lines of duplicated code **Checkout-Specific Features (alpic-ai#3):** - Add automatic session ID generation with crypto.randomUUID() - Add UseCheckoutOptions for custom session ID generator - Expose sessionId directly in useCheckout return value - Expose order directly in useCheckout return value - Maintain error discrimination with isCheckoutErrorResponse **Tests:** - Add 7 new tests for session ID generation and order access - All 95 tests passing (up from 88) - Full backward compatibility maintained 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Rodriguespn · 2026-01-06T23:53:56Z

Hey @fred! Thanks for the feedback and patience. I've addressed all your review points you mentioned besides the server tool implementation for ACP implementation:

Code Consolidation: Created a shared useAsyncOperation base hook that extracts the common async state management pattern. Both useCheckout and useCallTool now use this base, which eliminated around 80-100 lines of duplicated code. The refactor maintains full backward compatibility with all 95 tests passing.
Checkout-Specific Features: Added automatic session ID generation with crypto.randomUUID() that's overridable via the checkoutSessionIdGenerator option. The sessionId is now exposed directly in the hook's return value. Also changed the response to return order directly instead of nesting it in a data attribute. Added 7 new tests covering session ID generation and order access patterns.
Documentation: Removed all JSDoc and in-file comments from hook files. Improved the use-checkout.md documentation with comprehensive examples including session ID generation and a full API reference.
Maintenance: Upgraded biome from 2.3.10 to 2.3.11 to align with the version of the dev dependency on package.json. Also removed unused variables in packages/core/src/server/widgetsDevServer.ts that were causing format issues when running pnpm run test:format. Happy to revert these changes or open a new PR for them.

Removed the example app since is out of scope, removed in-file comments and moved them to proper docs, consolidated the shared codebase with the new base hook, and implemented the checkout-specific features you mentioned.

Regarding the ACP implementation for OpenAI's server tool, happy to tackle that in a separate PR later as you suggested.

fredericbarthelet · 2026-01-08T21:51:26Z

docs/docs/api-reference/use-checkout.md

+
+```tsx
+const {
+  data,


Do you still expose data in addition to order? I feel like this might be redundant

fredericbarthelet · 2026-01-08T21:54:23Z

docs/docs/api-reference/use-checkout.md

+        {isPending ? "Processing..." : "Checkout"}
+      </button>
+      {sessionId && <p>Session ID: {sessionId}</p>}
+      {isSuccess && order && (


Suggested change

{isSuccess && order && (

{isSuccess && (

I feel like isSuccess should be sufficient for order to be defined

fredericbarthelet · 2026-01-08T21:56:17Z

packages/core/src/server/widgetsDevServer.ts

  );

-  const { build, preview, ...devConfig } = configResult?.config || {};
+  const { ...devConfig } = configResult?.config || {};


I think you might have a conflicting version of biome on your IDE (or at least different that the one being used on this project). We experienced a few issues recently on that front: the extreme step of re downloading the project from Github did the trick for most of the team.

Anyhow, this should not be part of this PR

fredericbarthelet · 2026-01-08T21:58:16Z

packages/core/src/web/hooks/use-async-operation.test.ts

+      let resolveOperation: (value: string) => void;
+      const operationPromise = new Promise<string>((resolve) => {
+        resolveOperation = resolve;
+      });


You have a very convenient Promise syntax to create such "to be resolved" promise: Promise.withResolvers

fredericbarthelet · 2026-01-08T22:01:33Z

packages/core/src/web/hooks/use-async-operation.ts

+export type UseAsyncOperationConfig = {
+  enableDeduplication?: boolean;
+};


All the implementations of this hook seem to enable deduplication. I feel like this config parameter is not useful

fredericbarthelet · 2026-01-08T22:03:34Z

packages/core/src/web/hooks/use-async-operation.ts

+  error: TError;
+};
+
+export type AsyncOperationState<TData, TError = unknown> =


There is not a single location where AsyncOperationState is defined without its generic types, so you can drop the default generic value

Suggested change

export type AsyncOperationState<TData, TError = unknown> =

export type AsyncOperationState<TData, TError> =

fredericbarthelet · 2026-01-08T22:04:19Z

@greptile could you review again?

fredericbarthelet · 2026-01-08T22:06:18Z

packages/core/src/web/hooks/use-call-tool.ts

  const execute = async (
    toolArgs: ToolArgs,
  ): Promise<CombinedCallToolResponse> => {
-    const callId = ++callIdRef.current;
-    setCallToolState({ status: "pending", data: undefined, error: undefined });
-
-    try {
-      const data = await adaptor.callTool<ToolArgs, CombinedCallToolResponse>(
+    return executeAsync(async () => {
+      return adaptor.callTool<ToolArgs, CombinedCallToolResponse>(
        name,
        toolArgs,
      );
-      if (callId === callIdRef.current) {
-        setCallToolState({ status: "success", data, error: undefined });
-      }
-
-      return data;
-    } catch (error) {
-      if (callId === callIdRef.current) {
-        setCallToolState({ status: "error", data: undefined, error });
-      }
-      throw error;
-    }
+    });


why not use execute returned by useAsyncOperation directly and instead redefining a monad here?

Maybe it will be easier to understand if useAsyncOperation takes in the async callback as argument instead?

const { state, execute } = useAsyncOperation< CombinedCallToolResponse, unknown >((toolArgs) => adaptor.callTool(name, toolArgs));

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-08T22:08:05Z

packages/core/src/web/types.ts

+ * Checkout session request payload following the ACP specification.
+ */
+export type CheckoutSessionRequest = {
+  id: string;


The id field is marked as required, but useCheckout hook has logic to auto-generate IDs when not provided (line 83-85 in use-checkout.ts). This creates a type inconsistency where the hook expects id to be optional but the type declares it as required.

Consider making the field optional to match the actual behavior:

Suggested change

id: string;

id?: string;

This would align the type with the hook's auto-injection feature and eliminate the need for type assertions in tests (see line 332 in use-checkout.test.ts).

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-08T22:09:52Z

packages/core/src/web/hooks/use-checkout.ts

+        ? session
+        : { ...session, id: generateSessionId() };
+
+      setSessionId(sessionWithId.id);


setSessionId is called inside the async operation, which can lead to state inconsistency when deduplication is enabled. If a second checkout is initiated before the first completes, both will update sessionId, but only the second operation's result will be reflected in the state. This means sessionId could reference a session whose result was discarded due to deduplication.

greptile-apps · 2026-01-08T22:09:53Z

packages/core/src/server/widgetsDevServer.ts

  );

-  const { build, preview, ...devConfig } = configResult?.config || {};
+  const { ...devConfig } = configResult?.config || {};


Removing build and preview from destructuring means these properties will now be passed to createServer via ...devConfig. While Vite likely ignores unknown properties, this unrelated change wasn't mentioned in the PR description and could introduce unexpected behavior.

fredericbarthelet · 2026-01-08T22:13:10Z

packages/core/src/web/hooks/use-checkout.ts

+    return execute(session);
+  };
+
+  const requestCheckout: RequestCheckoutFn = ((


can't this be part of the useAsyncOperation as well? I feel like it's duplicated as well

fredericbarthelet

Hey @Rodriguespn thanks for your contribution. It's close to be ready!
I just shared a few comments to improve tests suite and useAsyncOperation hook. Let me know what you think of it

fredericbarthelet self-assigned this Dec 16, 2025

Rodriguespn force-pushed the feature/use-checkout-hook branch from 05e3525 to faa9ba7 Compare December 17, 2025 09:21

Rodriguespn marked this pull request as ready for review December 19, 2025 17:05

greptile-apps bot reviewed Dec 19, 2025

View reviewed changes

Rodriguespn force-pushed the feature/use-checkout-hook branch from 9ce2143 to 17007c5 Compare December 19, 2025 17:19

Rodriguespn force-pushed the feature/use-checkout-hook branch from 1d7666c to c781f67 Compare December 23, 2025 13:05

Rodriguespn and others added 8 commits January 6, 2026 22:21

first version of useCheckout hook

e8e4981

fix lint errors

1ae937d

docs: add useCheckout hook documentation

2439fa2

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

remove jsdocs

efbcc78

remove unused variables

997a388

migrate biome to v2.3.11

d906954

refactor: remove explanatory comments from hook files

8605a5d

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Rodriguespn force-pushed the feature/use-checkout-hook branch from c781f67 to 8605a5d Compare January 6, 2026 23:44

fredericbarthelet reviewed Jan 8, 2026

View reviewed changes

greptile-apps bot reviewed Jan 8, 2026

View reviewed changes

fredericbarthelet reviewed Jan 8, 2026

View reviewed changes

fredericbarthelet requested changes Jan 8, 2026

View reviewed changes

	export type AsyncOperationState<TData, TError = unknown> =
	export type AsyncOperationState<TData, TError> =

Conversation

Rodriguespn commented Dec 16, 2025 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Overview

Greptile Summary

Confidence Score: 4/5

Uh oh!

fredericbarthelet commented Dec 16, 2025

Uh oh!

Rodriguespn commented Dec 17, 2025

Uh oh!

greptile-apps bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Additional Comments (1)

Uh oh!

Rodriguespn commented Dec 19, 2025

Uh oh!

Rodriguespn commented Dec 31, 2025

Uh oh!

fredericbarthelet commented Dec 31, 2025

Uh oh!

Rodriguespn commented Jan 6, 2026

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fredericbarthelet Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

fredericbarthelet left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Rodriguespn commented Dec 16, 2025 •

edited by greptile-apps bot

Loading

greptile-apps bot left a comment •

edited

Loading

fredericbarthelet commented Jan 8, 2026 •

edited

Loading

fredericbarthelet Jan 8, 2026 •

edited

Loading

fredericbarthelet Jan 8, 2026 •

edited

Loading