@fmaplabs/shopify-app-convex-session-storage 0.1.0 → 0.1.2

package/README.md

@@ -2,9 +2,12 @@
 
 [![npm version](https://badge.fury.io/js/@fmaplabs%2Fshopify-app-convex-session-storage.svg)](https://badge.fury.io/js/@fmaplabs%2Fshopify-app-convex-session-storage)
 
-A [Convex component](https://docs.convex.dev/components) that provides Shopify session storage backed by a Convex database. Drop-in session persistence for Shopify apps built on Convex.
+A [Convex component](https://docs.convex.dev/components) that provides Shopify
+session storage backed by a Convex database. Drop-in session persistence for
+Shopify apps built on Convex.
 
-Found a bug? Feature request? [File it here](https://github.com/fmaplabs/shopify-app-convex-session-storage/issues).
+Found a bug? Feature request?
+[File it here](https://github.com/fmaplabs/shopify-app-convex-session-storage/issues).
 
 ## Installation
 
@@ -26,9 +29,18 @@ export default app;
 
 ## Usage
 
-Create a `ShopifySessionClient` instance and use it in your Convex functions:
+This package provides two ways to interact with session storage:
+
+- **`ShopifySessionClient`** — for use _inside_ Convex functions (server-side, via `ctx.runQuery`/`ctx.runMutation`)
+- **`ConvexSessionStorage`** — for use _outside_ Convex (your web server), implementing Shopify's [`SessionStorage`](https://github.com/Shopify/shopify-app-js/tree/main/packages/apps/session-storage/shopify-app-session-storage) interface
+
+### Step 1: Expose session functions in your Convex backend
+
+The component's internal functions can't be called over HTTP directly. Create
+public wrappers in your Convex backend using `ShopifySessionClient`:
 
 ```ts
+// convex/sessions.ts
 import { mutation, query } from "./_generated/server.js";
 import { components } from "./_generated/api.js";
 import { ShopifySessionClient } from "@fmaplabs/shopify-app-convex-session-storage";
@@ -42,9 +54,27 @@ export const storeSession = mutation({
   args: {
     id: v.string(),
     shop: v.string(),
+    state: v.optional(v.string()),
     isOnline: v.boolean(),
     scope: v.optional(v.string()),
+    expires: v.optional(v.string()),
     accessToken: v.optional(v.string()),
+    onlineAccessInfo: v.optional(
+      v.object({
+        expires_in: v.number(),
+        associated_user_scope: v.string(),
+        associated_user: v.object({
+          id: v.number(),
+          first_name: v.string(),
+          last_name: v.string(),
+          email: v.string(),
+          email_verified: v.boolean(),
+          account_owner: v.boolean(),
+          locale: v.string(),
+          collaborator: v.boolean(),
+        }),
+      }),
+    ),
   },
   handler: async (ctx, args) => {
     return await sessionClient.storeSession(ctx, args);
@@ -64,25 +94,126 @@ export const deleteSession = mutation({
     return await sessionClient.deleteSession(ctx, args);
   },
 });
+
+export const deleteSessions = mutation({
+  args: { ids: v.array(v.string()) },
+  handler: async (ctx, args) => {
+    return await sessionClient.deleteSessions(ctx, args);
+  },
+});
+
+export const findSessionsByShop = query({
+  args: { shop: v.string() },
+  handler: async (ctx, args) => {
+    return await sessionClient.findSessionsByShop(ctx, args);
+  },
+});
+```
+
+See [example/convex/example.ts](./example/convex/example.ts) for a complete
+example with additional helper functions.
+
+### Step 2: Use `ConvexSessionStorage` in your web server
+
+Pass `ConvexSessionStorage` to Shopify's `shopifyApp()` as the session storage
+adapter. It calls the public Convex functions you created above over HTTP.
+
+```sh
+npm install @shopify/shopify-api
+```
+
+#### With `ConvexHttpClient`
+
+```ts
+import { ConvexSessionStorage } from "@fmaplabs/shopify-app-convex-session-storage";
+import { ConvexHttpClient } from "convex/browser";
+import { api } from "../convex/_generated/api.js";
+
+const client = new ConvexHttpClient(process.env.CONVEX_URL!);
+
+export const sessionStorage = new ConvexSessionStorage(client, {
+  storeSession: api.sessions.storeSession,
+  loadSession: api.sessions.loadSession,
+  deleteSession: api.sessions.deleteSession,
+  deleteSessions: api.sessions.deleteSessions,
+  findSessionsByShop: api.sessions.findSessionsByShop,
+});
 ```
 
-See [example/convex/example.ts](./example/convex/example.ts) for a complete example.
+#### With Next.js `fetchQuery`/`fetchMutation`
+
+`ConvexSessionStorage` accepts any object with `query()` and `mutation()`
+methods, so you can wrap Convex's Next.js helpers:
+
+```ts
+import { ConvexSessionStorage } from "@fmaplabs/shopify-app-convex-session-storage";
+import { fetchQuery, fetchMutation } from "convex/nextjs";
+import { api } from "../convex/_generated/api.js";
+
+const client = {
+  query: (name: any, args: any) => fetchQuery(name, args),
+  mutation: (name: any, args: any) => fetchMutation(name, args),
+};
+
+export const sessionStorage = new ConvexSessionStorage(client, {
+  storeSession: api.sessions.storeSession,
+  loadSession: api.sessions.loadSession,
+  deleteSession: api.sessions.deleteSession,
+  deleteSessions: api.sessions.deleteSessions,
+  findSessionsByShop: api.sessions.findSessionsByShop,
+});
+```
+
+#### With `shopifyApp()`
+
+```ts
+import shopify from "@shopify/shopify-app-remix"; // or @shopify/shopify-app-express
+import { sessionStorage } from "./session-storage";
+
+const shopifyApp = shopify({
+  // ...other config
+  sessionStorage,
+});
+```
 
 ## API
 
 ### `ShopifySessionClient`
 
-| Method | Type | Description |
-|--------|------|-------------|
-| `loadSession(ctx, { id })` | query | Load a session by ID |
-| `storeSession(ctx, session)` | mutation | Create or update a session (upsert) |
-| `deleteSession(ctx, { id })` | mutation | Delete a session by ID |
-| `deleteSessions(ctx, { ids })` | mutation | Delete multiple sessions by ID |
-| `findSessionsByShop(ctx, { shop })` | query | Find all sessions for a shop |
-| `getOfflineSessionByShop(ctx, { shop })` | query | Get the offline session for a shop |
-| `deleteSessionsByShop(ctx, { shop })` | mutation | Delete all sessions for a shop |
-| `cleanupExpiredSessions(ctx)` | mutation | Delete all expired sessions |
-| `updateScopes(ctx, { id, scope })` | mutation | Update scopes on a session |
+For use inside Convex functions. Wraps the component's internal queries and
+mutations.
+
+| Method                                   | Type     | Description                         |
+| ---------------------------------------- | -------- | ----------------------------------- |
+| `loadSession(ctx, { id })`               | query    | Load a session by ID                |
+| `storeSession(ctx, session)`             | mutation | Create or update a session (upsert) |
+| `deleteSession(ctx, { id })`             | mutation | Delete a session by ID              |
+| `deleteSessions(ctx, { ids })`           | mutation | Delete multiple sessions by ID      |
+| `findSessionsByShop(ctx, { shop })`      | query    | Find all sessions for a shop        |
+| `getOfflineSessionByShop(ctx, { shop })` | query    | Get the offline session for a shop  |
+| `deleteSessionsByShop(ctx, { shop })`    | mutation | Delete all sessions for a shop      |
+| `cleanupExpiredSessions(ctx)`            | mutation | Delete all expired sessions         |
+| `updateScopes(ctx, { id, scope })`       | mutation | Update scopes on a session          |
+
+### `ConvexSessionStorage`
+
+For use outside Convex (web server). Implements Shopify's `SessionStorage`
+interface.
+
+```ts
+new ConvexSessionStorage(client, functionRefs);
+```
+
+- **`client`** — any object with `query(name, args)` and `mutation(name, args)` methods (e.g. `ConvexHttpClient`)
+- **`functionRefs`** — references to your 5 public Convex functions: `storeSession`, `loadSession`, `deleteSession`, `deleteSessions`, `findSessionsByShop`
+
+| Method                     | Description                              |
+| -------------------------- | ---------------------------------------- |
+| `storeSession(session)`    | Store a Shopify `Session` object         |
+| `loadSession(id)`          | Load a session, returns `Session` or `undefined` |
+| `deleteSession(id)`        | Delete a session by ID                   |
+| `deleteSessions(ids)`      | Delete multiple sessions by ID           |
+| `findSessionsByShop(shop)` | Find all sessions for a shop             |
 
 ### Types
 
@@ -92,6 +223,8 @@ import type {
   ShopifySessionInput,
   OnlineAccessInfo,
   AssociatedUser,
+  ConvexSessionClient,
+  SessionFunctionRefs,
 } from "@fmaplabs/shopify-app-convex-session-storage";
 ```
 
@@ -107,3 +240,26 @@ Run tests:
 ```sh
 npm test
 ```
+
+### License
+
+MIT License
+
+Copyright (c) 2026 fmap labs
+
+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/dist/client/index.d.ts

@@ -1,6 +1,7 @@
 import type { GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
 import type { ComponentApi } from "../component/_generated/component.js";
 export type { ComponentApi };
+export { ConvexSessionStorage, type ConvexSessionClient, type SessionFunctionRefs, } from "./session-storage.js";
 export type AssociatedUser = {
     id: number;
     first_name: string;

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,cAAc,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC,CAAC;AAEF,KAAK,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,UAAU,CAAC,CAAC;AACpE,KAAK,WAAW,GAAG,IAAI,CACrB,kBAAkB,CAAC,gBAAgB,CAAC,EACpC,UAAU,GAAG,aAAa,CAC3B,CAAC;AAEF,qBAAa,oBAAoB;IACZ,SAAS,EAAE,YAAY;gBAAvB,SAAS,EAAE,YAAY;IAEpC,WAAW,CACf,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GACnB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI3B,YAAY,CAChB,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAIV,aAAa,CACjB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GACnB,OAAO,CAAC,OAAO,CAAC;IAIb,cAAc,CAClB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,GACtB,OAAO,CAAC,OAAO,CAAC;IAIb,kBAAkB,CACtB,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GACrB,OAAO,CAAC,cAAc,EAAE,CAAC;IAItB,uBAAuB,CAC3B,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GACrB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAO3B,oBAAoB,CACxB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GACrB,OAAO,CAAC,IAAI,CAAC;IAIV,sBAAsB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzD,YAAY,CAChB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAClC,OAAO,CAAC,OAAO,CAAC;CAGpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/index.js

@@ -1,3 +1,4 @@
+export { ConvexSessionStorage, } from "./session-storage.js";
 export class ShopifySessionClient {
     component;
     constructor(component) {

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAwDA,MAAM,OAAO,oBAAoB;IACZ;IAAnB,YAAmB,SAAuB;QAAvB,cAAS,GAAT,SAAS,CAAc;IAAG,CAAC;IAE9C,KAAK,CAAC,WAAW,CACf,GAAa,EACb,IAAoB;QAEpB,OAAO,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,GAAgB,EAChB,OAA4B;QAE5B,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,GAAgB,EAChB,IAAoB;QAEpB,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,GAAgB,EAChB,IAAuB;QAEvB,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,kBAAkB,CACtB,GAAa,EACb,IAAsB;QAEtB,OAAO,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,uBAAuB,CAC3B,GAAa,EACb,IAAsB;QAEtB,OAAO,MAAM,GAAG,CAAC,QAAQ,CACvB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,EAC1C,IAAI,CACL,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,oBAAoB,CACxB,GAAgB,EAChB,IAAsB;QAEtB,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,sBAAsB,CAAC,GAAgB;QAC3C,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,GAAgB,EAChB,IAAmC;QAEnC,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAC;AAiD9B,MAAM,OAAO,oBAAoB;IACZ;IAAnB,YAAmB,SAAuB;QAAvB,cAAS,GAAT,SAAS,CAAc;IAAG,CAAC;IAE9C,KAAK,CAAC,WAAW,CACf,GAAa,EACb,IAAoB;QAEpB,OAAO,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,GAAgB,EAChB,OAA4B;QAE5B,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,GAAgB,EAChB,IAAoB;QAEpB,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,GAAgB,EAChB,IAAuB;QAEvB,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,kBAAkB,CACtB,GAAa,EACb,IAAsB;QAEtB,OAAO,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,uBAAuB,CAC3B,GAAa,EACb,IAAsB;QAEtB,OAAO,MAAM,GAAG,CAAC,QAAQ,CACvB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,EAC1C,IAAI,CACL,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,oBAAoB,CACxB,GAAgB,EAChB,IAAsB;QAEtB,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,sBAAsB,CAAC,GAAgB;QAC3C,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,GAAgB,EAChB,IAAmC;QAEnC,OAAO,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;CACF"}

package/dist/client/session-storage.d.ts

@@ -0,0 +1,51 @@
+import { Session } from "@shopify/shopify-api";
+import type { SessionStorage } from "@shopify/shopify-app-session-storage";
+/**
+ * Minimal client contract compatible with ConvexHttpClient, fetchQuery/fetchMutation wrappers,
+ * or any custom implementation.
+ */
+export interface ConvexSessionClient {
+    query<Output>(name: string | {
+        _returnType: Output;
+    }, args: Record<string, unknown>): Promise<Output>;
+    mutation<Output>(name: string | {
+        _returnType: Output;
+    }, args: Record<string, unknown>): Promise<Output>;
+}
+/**
+ * References to the consumer's public Convex functions that wrap the component's
+ * internal session CRUD operations.
+ */
+export interface SessionFunctionRefs {
+    storeSession: string | {
+        _returnType: unknown;
+        _args: unknown;
+    };
+    loadSession: string | {
+        _returnType: unknown;
+        _args: unknown;
+    };
+    deleteSession: string | {
+        _returnType: unknown;
+        _args: unknown;
+    };
+    deleteSessions: string | {
+        _returnType: unknown;
+        _args: unknown;
+    };
+    findSessionsByShop: string | {
+        _returnType: unknown;
+        _args: unknown;
+    };
+}
+export declare class ConvexSessionStorage implements SessionStorage {
+    private client;
+    private fns;
+    constructor(client: ConvexSessionClient, fns: SessionFunctionRefs);
+    storeSession(session: Session): Promise<boolean>;
+    loadSession(id: string): Promise<Session | undefined>;
+    deleteSession(id: string): Promise<boolean>;
+    deleteSessions(ids: string[]): Promise<boolean>;
+    findSessionsByShop(shop: string): Promise<Session[]>;
+}
+//# sourceMappingURL=session-storage.d.ts.map

package/dist/client/session-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.d.ts","sourceRoot":"","sources":["../../src/client/session-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAG3E;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,MAAM,EACV,IAAI,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,EACb,IAAI,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAChE,WAAW,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/D,aAAa,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IACjE,cAAc,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAClE,kBAAkB,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CACvE;AAiDD,qBAAa,oBAAqB,YAAW,cAAc;IAEvD,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;gBADH,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,mBAAmB;IAG5B,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IASrD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3C,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAO/C,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAO3D"}

package/dist/client/session-storage.js

@@ -0,0 +1,71 @@
+import { Session } from "@shopify/shopify-api";
+function sessionToInput(session) {
+    return {
+        id: session.id,
+        shop: session.shop,
+        state: session.state,
+        isOnline: session.isOnline,
+        scope: session.scope,
+        expires: session.expires ? session.expires.toISOString() : undefined,
+        accessToken: session.accessToken,
+        onlineAccessInfo: session.onlineAccessInfo?.associated_user
+            ? {
+                expires_in: session.onlineAccessInfo.expires_in,
+                associated_user_scope: session.onlineAccessInfo.associated_user_scope,
+                associated_user: {
+                    id: session.onlineAccessInfo.associated_user.id,
+                    first_name: session.onlineAccessInfo.associated_user.first_name,
+                    last_name: session.onlineAccessInfo.associated_user.last_name,
+                    email: session.onlineAccessInfo.associated_user.email,
+                    email_verified: session.onlineAccessInfo.associated_user.email_verified,
+                    account_owner: session.onlineAccessInfo.associated_user.account_owner,
+                    locale: session.onlineAccessInfo.associated_user.locale,
+                    collaborator: session.onlineAccessInfo.associated_user.collaborator,
+                },
+            }
+            : undefined,
+    };
+}
+function dataToSession(data) {
+    return new Session({
+        id: data.id,
+        shop: data.shop,
+        state: data.state ?? "",
+        isOnline: data.isOnline,
+        scope: data.scope,
+        expires: data.expires ? new Date(data.expires) : undefined,
+        accessToken: data.accessToken,
+        onlineAccessInfo: data.onlineAccessInfo,
+    });
+}
+// TODO: Implement the ConvexSessionStorage class
+// See the plan description above for guidance on the 5 required SessionStorage methods.
+export class ConvexSessionStorage {
+    client;
+    fns;
+    constructor(client, fns) {
+        this.client = client;
+        this.fns = fns;
+    }
+    async storeSession(session) {
+        await this.client.mutation(this.fns.storeSession, sessionToInput(session));
+        return true;
+    }
+    async loadSession(id) {
+        const data = await this.client.query(this.fns.loadSession, { id });
+        if (!data)
+            return undefined;
+        return dataToSession(data);
+    }
+    async deleteSession(id) {
+        return await this.client.mutation(this.fns.deleteSession, { id });
+    }
+    async deleteSessions(ids) {
+        return await this.client.mutation(this.fns.deleteSessions, { ids });
+    }
+    async findSessionsByShop(shop) {
+        const sessions = await this.client.query(this.fns.findSessionsByShop, { shop });
+        return sessions.map(dataToSession);
+    }
+}
+//# sourceMappingURL=session-storage.js.map

package/dist/client/session-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.js","sourceRoot":"","sources":["../../src/client/session-storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,101 +1,111 @@
 {
-  "name": "@fmaplabs/shopify-app-convex-session-storage",
-  "description": "Shopify session storage backed by Convex, as a Convex component.",
-  "repository": "github:fmaplabs/shopify-app-convex-session-storage",
-  "homepage": "https://github.com/fmaplabs/shopify-app-convex-session-storage#readme",
-  "bugs": {
-    "url": "https://github.com/fmaplabs/shopify-app-convex-session-storage/issues"
-  },
-  "version": "0.1.0",
-  "license": "Apache-2.0",
-  "keywords": [
-    "convex",
-    "component",
-    "shopify",
-    "session-storage"
-  ],
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "dev": "run-p -r 'dev:*'",
-    "dev:backend": "convex dev --typecheck-components",
-    "dev:frontend": "cd example && vite --clearScreen false",
-    "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build:codegen' --initial",
-    "predev": "path-exists .env.local dist || (npm run build && convex dev --once)",
-    "build": "tsc --project ./tsconfig.build.json",
-    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
-    "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
-    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
-    "lint": "eslint .",
-    "all": "run-p -r 'dev:*' 'test:watch'",
-    "test": "vitest run --typecheck",
-    "test:watch": "vitest --typecheck --clearScreen false",
-    "test:debug": "vitest --inspect-brk --no-file-parallelism",
-    "test:coverage": "vitest run --coverage --coverage.reporter=text",
-    "preversion": "npm ci && npm run build:clean && run-p test lint typecheck",
-    "prepublishOnly": "npm whoami || npm login",
-    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
-    "release": "npm version patch && npm publish && git push --follow-tags",
-    "version": "vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
-  },
-  "files": [
-    "dist",
-    "src"
-  ],
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/client/index.d.ts",
-      "default": "./dist/client/index.js"
+    "name": "@fmaplabs/shopify-app-convex-session-storage",
+    "description": "Shopify session storage backed by Convex, as a Convex component.",
+    "repository": "github:fmaplabs/shopify-app-convex-session-storage",
+    "homepage": "https://github.com/fmaplabs/shopify-app-convex-session-storage#readme",
+    "bugs": {
+        "url": "https://github.com/fmaplabs/shopify-app-convex-session-storage/issues"
     },
-    "./test": "./src/test.ts",
-    "./_generated/component.js": {
-      "types": "./dist/component/_generated/component.d.ts"
+    "version": "0.1.2",
+    "license": "MIT",
+    "keywords": [
+        "convex",
+        "component",
+        "shopify",
+        "session-storage"
+    ],
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
     },
-    "./_generated/component": {
-      "types": "./dist/component/_generated/component.d.ts"
+    "scripts": {
+        "dev": "run-p -r 'dev:*'",
+        "dev:backend": "convex dev --typecheck-components",
+        "dev:frontend": "cd example && vite --clearScreen false",
+        "dev:build": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.ts' -c 'npm run build:codegen' --initial",
+        "predev": "path-exists .env.local dist || (npm run build && convex dev --once)",
+        "build": "tsc --project ./tsconfig.build.json",
+        "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+        "build:clean": "rm -rf dist *.tsbuildinfo && npm run build:codegen",
+        "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+        "lint": "eslint .",
+        "all": "run-p -r 'dev:*' 'test:watch'",
+        "test": "vitest run --typecheck",
+        "test:watch": "vitest --typecheck --clearScreen false",
+        "test:debug": "vitest --inspect-brk --no-file-parallelism",
+        "test:coverage": "vitest run --coverage --coverage.reporter=text",
+        "preversion": "npm ci && npm run build:clean && run-p test lint typecheck",
+        "prepublishOnly": "npm whoami || npm login",
+        "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+        "release": "npm version patch && npm publish && git push --follow-tags",
+        "version": "vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
     },
-    "./convex.config.js": {
-      "types": "./dist/component/convex.config.d.ts",
-      "default": "./dist/component/convex.config.js"
+    "files": [
+        "dist",
+        "src"
+    ],
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/client/index.d.ts",
+            "default": "./dist/client/index.js"
+        },
+        "./test": "./src/test.ts",
+        "./_generated/component.js": {
+            "types": "./dist/component/_generated/component.d.ts"
+        },
+        "./_generated/component": {
+            "types": "./dist/component/_generated/component.d.ts"
+        },
+        "./convex.config.js": {
+            "types": "./dist/component/convex.config.d.ts",
+            "default": "./dist/component/convex.config.js"
+        },
+        "./convex.config": {
+            "types": "./dist/component/convex.config.d.ts",
+            "default": "./dist/component/convex.config.js"
+        }
     },
-    "./convex.config": {
-      "types": "./dist/component/convex.config.d.ts",
-      "default": "./dist/component/convex.config.js"
+    "peerDependencies": {
+        "convex": "^1.31.7",
+        "@shopify/shopify-api": "^12.0.0"
+    },
+    "peerDependenciesMeta": {
+        "@shopify/shopify-api": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@convex-dev/eslint-plugin": "^1.1.1",
+        "@edge-runtime/vm": "^5.0.0",
+        "@eslint/eslintrc": "^3.3.3",
+        "@eslint/js": "9.39.2",
+        "@shopify/shopify-api": "^12.3.0",
+        "@types/node": "^24.10.11",
+        "@types/react": "^19.2.13",
+        "@types/react-dom": "^19.2.3",
+        "@vitejs/plugin-react": "^5.1.3",
+        "chokidar-cli": "3.0.0",
+        "convex": "1.31.7",
+        "convex-test": "0.0.41",
+        "eslint": "9.39.2",
+        "eslint-plugin-react-hooks": "^7.0.1",
+        "eslint-plugin-react-refresh": "^0.5.0",
+        "globals": "^17.3.0",
+        "npm-run-all2": "8.0.4",
+        "path-exists-cli": "2.0.0",
+        "pkg-pr-new": "^0.0.63",
+        "prettier": "3.8.1",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
+        "typescript": "5.9.3",
+        "typescript-eslint": "8.54.0",
+        "vite": "7.3.1",
+        "vitest": "4.0.18"
+    },
+    "types": "./dist/client/index.d.ts",
+    "module": "./dist/client/index.js",
+    "dependencies": {
+        "@shopify/shopify-app-session-storage": "^4.0.5"
     }
-  },
-  "peerDependencies": {
-    "convex": "^1.31.7"
-  },
-  "devDependencies": {
-    "@convex-dev/eslint-plugin": "^1.1.1",
-    "@edge-runtime/vm": "^5.0.0",
-    "@eslint/eslintrc": "^3.3.3",
-    "@eslint/js": "9.39.2",
-    "@types/node": "^24.10.11",
-    "@types/react": "^19.2.13",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.3",
-    "chokidar-cli": "3.0.0",
-    "convex": "1.31.7",
-    "convex-test": "0.0.41",
-    "eslint": "9.39.2",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.5.0",
-    "globals": "^17.3.0",
-    "npm-run-all2": "8.0.4",
-    "path-exists-cli": "2.0.0",
-    "pkg-pr-new": "^0.0.63",
-    "prettier": "3.8.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.54.0",
-    "vite": "7.3.1",
-    "vitest": "4.0.18"
-  },
-  "types": "./dist/client/index.d.ts",
-  "module": "./dist/client/index.js"
-}
+}

package/src/client/index.ts

@@ -6,6 +6,11 @@ import type {
 import type { ComponentApi } from "../component/_generated/component.js";
 
 export type { ComponentApi };
+export {
+  ConvexSessionStorage,
+  type ConvexSessionClient,
+  type SessionFunctionRefs,
+} from "./session-storage.js";
 
 export type AssociatedUser = {
   id: number;

package/src/client/session-storage.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, test, vi } from "vitest";
+import { Session } from "@shopify/shopify-api";
+import {
+  ConvexSessionStorage,
+  type ConvexSessionClient,
+} from "./session-storage.js";
+import type { ShopifySession } from "./index.js";
+
+function createMockClient() {
+  return {
+    query: vi.fn(),
+    mutation: vi.fn(),
+  } satisfies ConvexSessionClient;
+}
+
+const fns = {
+  storeSession: "sessions:storeSession",
+  loadSession: "sessions:loadSession",
+  deleteSession: "sessions:deleteSession",
+  deleteSessions: "sessions:deleteSessions",
+  findSessionsByShop: "sessions:findSessionsByShop",
+};
+
+describe("ConvexSessionStorage", () => {
+  test("storeSession converts Date to ISO string", async () => {
+    const client = createMockClient();
+    client.mutation.mockResolvedValue(null);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const expires = new Date("2025-06-01T00:00:00.000Z");
+    const session = new Session({
+      id: "offline_shop.myshopify.com",
+      shop: "shop.myshopify.com",
+      state: "abc123",
+      isOnline: false,
+      scope: "read_products",
+      accessToken: "shpat_test",
+      expires,
+    });
+
+    const result = await storage.storeSession(session);
+
+    expect(result).toBe(true);
+    expect(client.mutation).toHaveBeenCalledWith(fns.storeSession, {
+      id: "offline_shop.myshopify.com",
+      shop: "shop.myshopify.com",
+      state: "abc123",
+      isOnline: false,
+      scope: "read_products",
+      accessToken: "shpat_test",
+      expires: "2025-06-01T00:00:00.000Z",
+      onlineAccessInfo: undefined,
+    });
+  });
+
+  test("storeSession maps onlineAccessInfo correctly", async () => {
+    const client = createMockClient();
+    client.mutation.mockResolvedValue(null);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const session = new Session({
+      id: "online_shop.myshopify.com_1",
+      shop: "shop.myshopify.com",
+      state: "xyz",
+      isOnline: true,
+      onlineAccessInfo: {
+        expires_in: 86400,
+        associated_user_scope: "read_products",
+        associated_user: {
+          id: 123,
+          first_name: "John",
+          last_name: "Doe",
+          email: "john@example.com",
+          email_verified: true,
+          account_owner: true,
+          locale: "en",
+          collaborator: false,
+        },
+      },
+    });
+
+    await storage.storeSession(session);
+
+    const args = client.mutation.mock.calls[0]![1];
+    expect(args.onlineAccessInfo).toEqual({
+      expires_in: 86400,
+      associated_user_scope: "read_products",
+      associated_user: {
+        id: 123,
+        first_name: "John",
+        last_name: "Doe",
+        email: "john@example.com",
+        email_verified: true,
+        account_owner: true,
+        locale: "en",
+        collaborator: false,
+      },
+    });
+  });
+
+  test("loadSession converts ISO string to Date and returns Session instance", async () => {
+    const client = createMockClient();
+    const stored: ShopifySession = {
+      _id: "conv_abc",
+      _creationTime: 1234567890,
+      id: "offline_shop.myshopify.com",
+      shop: "shop.myshopify.com",
+      state: "abc123",
+      isOnline: false,
+      scope: "read_products",
+      accessToken: "shpat_test",
+      expires: "2025-06-01T00:00:00.000Z",
+    };
+    client.query.mockResolvedValue(stored);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const session = await storage.loadSession("offline_shop.myshopify.com");
+
+    expect(session).toBeInstanceOf(Session);
+    expect(session!.id).toBe("offline_shop.myshopify.com");
+    expect(session!.shop).toBe("shop.myshopify.com");
+    expect(session!.expires).toEqual(new Date("2025-06-01T00:00:00.000Z"));
+    expect(session!.accessToken).toBe("shpat_test");
+  });
+
+  test("loadSession returns undefined for missing session", async () => {
+    const client = createMockClient();
+    client.query.mockResolvedValue(null);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const session = await storage.loadSession("nonexistent");
+
+    expect(session).toBeUndefined();
+  });
+
+  test("loadSession defaults state to empty string", async () => {
+    const client = createMockClient();
+    const stored: ShopifySession = {
+      _id: "conv_abc",
+      _creationTime: 1234567890,
+      id: "test_id",
+      shop: "shop.myshopify.com",
+      isOnline: false,
+      // state is undefined
+    };
+    client.query.mockResolvedValue(stored);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const session = await storage.loadSession("test_id");
+
+    expect(session!.state).toBe("");
+  });
+
+  test("deleteSession passes through correctly", async () => {
+    const client = createMockClient();
+    client.mutation.mockResolvedValue(true);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const result = await storage.deleteSession("offline_shop.myshopify.com");
+
+    expect(result).toBe(true);
+    expect(client.mutation).toHaveBeenCalledWith(fns.deleteSession, {
+      id: "offline_shop.myshopify.com",
+    });
+  });
+
+  test("deleteSessions passes through correctly", async () => {
+    const client = createMockClient();
+    client.mutation.mockResolvedValue(true);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const result = await storage.deleteSessions(["id1", "id2"]);
+
+    expect(result).toBe(true);
+    expect(client.mutation).toHaveBeenCalledWith(fns.deleteSessions, {
+      ids: ["id1", "id2"],
+    });
+  });
+
+  test("findSessionsByShop converts all results to Session instances", async () => {
+    const client = createMockClient();
+    const stored: ShopifySession[] = [
+      {
+        _id: "conv_1",
+        _creationTime: 1234567890,
+        id: "offline_shop.myshopify.com",
+        shop: "shop.myshopify.com",
+        isOnline: false,
+        scope: "read_products",
+      },
+      {
+        _id: "conv_2",
+        _creationTime: 1234567891,
+        id: "online_shop.myshopify.com_1",
+        shop: "shop.myshopify.com",
+        isOnline: true,
+      },
+    ];
+    client.query.mockResolvedValue(stored);
+    const storage = new ConvexSessionStorage(client, fns);
+
+    const sessions = await storage.findSessionsByShop("shop.myshopify.com");
+
+    expect(sessions).toHaveLength(2);
+    expect(sessions[0]).toBeInstanceOf(Session);
+    expect(sessions[1]).toBeInstanceOf(Session);
+    expect(sessions[0]!.id).toBe("offline_shop.myshopify.com");
+    expect(sessions[1]!.id).toBe("online_shop.myshopify.com_1");
+  });
+});

package/src/client/session-storage.ts

@@ -0,0 +1,120 @@
+import { Session } from "@shopify/shopify-api";
+import type { SessionStorage } from "@shopify/shopify-app-session-storage";
+import type { ShopifySession, ShopifySessionInput } from "./index.js";
+
+/**
+ * Minimal client contract compatible with ConvexHttpClient, fetchQuery/fetchMutation wrappers,
+ * or any custom implementation.
+ */
+export interface ConvexSessionClient {
+  query<Output>(
+    name: string | { _returnType: Output },
+    args: Record<string, unknown>,
+  ): Promise<Output>;
+  mutation<Output>(
+    name: string | { _returnType: Output },
+    args: Record<string, unknown>,
+  ): Promise<Output>;
+}
+
+/**
+ * References to the consumer's public Convex functions that wrap the component's
+ * internal session CRUD operations.
+ */
+export interface SessionFunctionRefs {
+  storeSession: string | { _returnType: unknown; _args: unknown };
+  loadSession: string | { _returnType: unknown; _args: unknown };
+  deleteSession: string | { _returnType: unknown; _args: unknown };
+  deleteSessions: string | { _returnType: unknown; _args: unknown };
+  findSessionsByShop: string | { _returnType: unknown; _args: unknown };
+}
+
+function sessionToInput(session: Session): ShopifySessionInput {
+  return {
+    id: session.id,
+    shop: session.shop,
+    state: session.state,
+    isOnline: session.isOnline,
+    scope: session.scope,
+    expires: session.expires ? session.expires.toISOString() : undefined,
+    accessToken: session.accessToken,
+    onlineAccessInfo: session.onlineAccessInfo?.associated_user
+      ? {
+          expires_in: session.onlineAccessInfo.expires_in,
+          associated_user_scope:
+            session.onlineAccessInfo.associated_user_scope,
+          associated_user: {
+            id: session.onlineAccessInfo.associated_user.id,
+            first_name: session.onlineAccessInfo.associated_user.first_name,
+            last_name: session.onlineAccessInfo.associated_user.last_name,
+            email: session.onlineAccessInfo.associated_user.email,
+            email_verified:
+              session.onlineAccessInfo.associated_user.email_verified,
+            account_owner:
+              session.onlineAccessInfo.associated_user.account_owner,
+            locale: session.onlineAccessInfo.associated_user.locale,
+            collaborator:
+              session.onlineAccessInfo.associated_user.collaborator,
+          },
+        }
+      : undefined,
+  };
+}
+
+function dataToSession(data: ShopifySession): Session {
+  return new Session({
+    id: data.id,
+    shop: data.shop,
+    state: data.state ?? "",
+    isOnline: data.isOnline,
+    scope: data.scope,
+    expires: data.expires ? new Date(data.expires) : undefined,
+    accessToken: data.accessToken,
+    onlineAccessInfo: data.onlineAccessInfo,
+  });
+}
+
+// TODO: Implement the ConvexSessionStorage class
+// See the plan description above for guidance on the 5 required SessionStorage methods.
+export class ConvexSessionStorage implements SessionStorage {
+  constructor(
+    private client: ConvexSessionClient,
+    private fns: SessionFunctionRefs,
+  ) {}
+
+  async storeSession(session: Session): Promise<boolean> {
+    await this.client.mutation(this.fns.storeSession as string, sessionToInput(session));
+    return true;
+  }
+
+  async loadSession(id: string): Promise<Session | undefined> {
+    const data = await this.client.query<ShopifySession | null>(
+      this.fns.loadSession as string,
+      { id },
+    );
+    if (!data) return undefined;
+    return dataToSession(data);
+  }
+
+  async deleteSession(id: string): Promise<boolean> {
+    return await this.client.mutation<boolean>(
+      this.fns.deleteSession as string,
+      { id },
+    );
+  }
+
+  async deleteSessions(ids: string[]): Promise<boolean> {
+    return await this.client.mutation<boolean>(
+      this.fns.deleteSessions as string,
+      { ids },
+    );
+  }
+
+  async findSessionsByShop(shop: string): Promise<Session[]> {
+    const sessions = await this.client.query<ShopifySession[]>(
+      this.fns.findSessionsByShop as string,
+      { shop },
+    );
+    return sessions.map(dataToSession);
+  }
+}

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1.  Definitions.
-
-    "License" shall mean the terms and conditions for use, reproduction,
-    and distribution as defined by Sections 1 through 9 of this document.
-
-    "Licensor" shall mean the copyright owner or entity authorized by
-    the copyright owner that is granting the License.
-
-    "Legal Entity" shall mean the union of the acting entity and all
-    other entities that control, are controlled by, or are under common
-    control with that entity. For the purposes of this definition,
-    "control" means (i) the power, direct or indirect, to cause the
-    direction or management of such entity, whether by contract or
-    otherwise, or (ii) ownership of fifty percent (50%) or more of the
-    outstanding shares, or (iii) beneficial ownership of such entity.
-
-    "You" (or "Your") shall mean an individual or Legal Entity
-    exercising permissions granted by this License.
-
-    "Source" form shall mean the preferred form for making modifications,
-    including but not limited to software source code, documentation
-    source, and configuration files.
-
-    "Object" form shall mean any form resulting from mechanical
-    transformation or translation of a Source form, including but
-    not limited to compiled object code, generated documentation,
-    and conversions to other media types.
-
-    "Work" shall mean the work of authorship, whether in Source or
-    Object form, made available under the License, as indicated by a
-    copyright notice that is included in or attached to the work
-    (an example is provided in the Appendix below).
-
-    "Derivative Works" shall mean any work, whether in Source or Object
-    form, that is based on (or derived from) the Work and for which the
-    editorial revisions, annotations, elaborations, or other modifications
-    represent, as a whole, an original work of authorship. For the purposes
-    of this License, Derivative Works shall not include works that remain
-    separable from, or merely link (or bind by name) to the interfaces of,
-    the Work and Derivative Works thereof.
-
-    "Contribution" shall mean any work of authorship, including
-    the original version of the Work and any modifications or additions
-    to that Work or Derivative Works thereof, that is intentionally
-    submitted to Licensor for inclusion in the Work by the copyright owner
-    or by an individual or Legal Entity authorized to submit on behalf of
-    the copyright owner. For the purposes of this definition, "submitted"
-    means any form of electronic, verbal, or written communication sent
-    to the Licensor or its representatives, including but not limited to
-    communication on electronic mailing lists, source code control systems,
-    and issue tracking systems that are managed by, or on behalf of, the
-    Licensor for the purpose of discussing and improving the Work, but
-    excluding communication that is conspicuously marked or otherwise
-    designated in writing by the copyright owner as "Not a Contribution."
-
-    "Contributor" shall mean Licensor and any individual or Legal Entity
-    on behalf of whom a Contribution has been received by Licensor and
-    subsequently incorporated within the Work.
-
-2.  Grant of Copyright License. Subject to the terms and conditions of
-    this License, each Contributor hereby grants to You a perpetual,
-    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-    copyright license to reproduce, prepare Derivative Works of,
-    publicly display, publicly perform, sublicense, and distribute the
-    Work and such Derivative Works in Source or Object form.
-
-3.  Grant of Patent License. Subject to the terms and conditions of
-    this License, each Contributor hereby grants to You a perpetual,
-    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-    (except as stated in this section) patent license to make, have made,
-    use, offer to sell, sell, import, and otherwise transfer the Work,
-    where such license applies only to those patent claims licensable
-    by such Contributor that are necessarily infringed by their
-    Contribution(s) alone or by combination of their Contribution(s)
-    with the Work to which such Contribution(s) was submitted. If You
-    institute patent litigation against any entity (including a
-    cross-claim or counterclaim in a lawsuit) alleging that the Work
-    or a Contribution incorporated within the Work constitutes direct
-    or contributory patent infringement, then any patent licenses
-    granted to You under this License for that Work shall terminate
-    as of the date such litigation is filed.
-
-4.  Redistribution. You may reproduce and distribute copies of the
-    Work or Derivative Works thereof in any medium, with or without
-    modifications, and in Source or Object form, provided that You
-    meet the following conditions:
-
-    (a) You must give any other recipients of the Work or
-    Derivative Works a copy of this License; and
-
-    (b) You must cause any modified files to carry prominent notices
-    stating that You changed the files; and
-
-    (c) You must retain, in the Source form of any Derivative Works
-    that You distribute, all copyright, patent, trademark, and
-    attribution notices from the Source form of the Work,
-    excluding those notices that do not pertain to any part of
-    the Derivative Works; and
-
-    (d) If the Work includes a "NOTICE" text file as part of its
-    distribution, then any Derivative Works that You distribute must
-    include a readable copy of the attribution notices contained
-    within such NOTICE file, excluding those notices that do not
-    pertain to any part of the Derivative Works, in at least one
-    of the following places: within a NOTICE text file distributed
-    as part of the Derivative Works; within the Source form or
-    documentation, if provided along with the Derivative Works; or,
-    within a display generated by the Derivative Works, if and
-    wherever such third-party notices normally appear. The contents
-    of the NOTICE file are for informational purposes only and
-    do not modify the License. You may add Your own attribution
-    notices within Derivative Works that You distribute, alongside
-    or as an addendum to the NOTICE text from the Work, provided
-    that such additional attribution notices cannot be construed
-    as modifying the License.
-
-    You may add Your own copyright statement to Your modifications and
-    may provide additional or different license terms and conditions
-    for use, reproduction, or distribution of Your modifications, or
-    for any such Derivative Works as a whole, provided Your use,
-    reproduction, and distribution of the Work otherwise complies with
-    the conditions stated in this License.
-
-5.  Submission of Contributions. Unless You explicitly state otherwise,
-    any Contribution intentionally submitted for inclusion in the Work
-    by You to the Licensor shall be under the terms and conditions of
-    this License, without any additional terms or conditions.
-    Notwithstanding the above, nothing herein shall supersede or modify
-    the terms of any separate license agreement you may have executed
-    with Licensor regarding such Contributions.
-
-6.  Trademarks. This License does not grant permission to use the trade
-    names, trademarks, service marks, or product names of the Licensor,
-    except as required for reasonable and customary use in describing the
-    origin of the Work and reproducing the content of the NOTICE file.
-
-7.  Disclaimer of Warranty. Unless required by applicable law or
-    agreed to in writing, Licensor provides the Work (and each
-    Contributor provides its Contributions) on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-    implied, including, without limitation, any warranties or conditions
-    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-    PARTICULAR PURPOSE. You are solely responsible for determining the
-    appropriateness of using or redistributing the Work and assume any
-    risks associated with Your exercise of permissions under this License.
-
-8.  Limitation of Liability. In no event and under no legal theory,
-    whether in tort (including negligence), contract, or otherwise,
-    unless required by applicable law (such as deliberate and grossly
-    negligent acts) or agreed to in writing, shall any Contributor be
-    liable to You for damages, including any direct, indirect, special,
-    incidental, or consequential damages of any character arising as a
-    result of this License or out of the use or inability to use the
-    Work (including but not limited to damages for loss of goodwill,
-    work stoppage, computer failure or malfunction, or any and all
-    other commercial damages or losses), even if such Contributor
-    has been advised of the possibility of such damages.
-
-9.  Accepting Warranty or Additional Liability. While redistributing
-    the Work or Derivative Works thereof, You may choose to offer,
-    and charge a fee for, acceptance of support, warranty, indemnity,
-    or other liability obligations and/or rights consistent with this
-    License. However, in accepting such obligations, You may act only
-    on Your own behalf and on Your sole responsibility, not on behalf
-    of any other Contributor, and only if You agree to indemnify,
-    defend, and hold each Contributor harmless for any liability
-    incurred by, or claims asserted against, such Contributor by reason
-    of your accepting any such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS
-
-APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-Copyright [yyyy] [name of copyright owner]
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.