@jay-framework/wix-server-client 0.15.0

package/README.md

@@ -0,0 +1,203 @@
+# @jay-framework/wix-server-client
+
+A Wix SDK client for the Jay Framework with support for both server-side API Key authentication and client-side OAuth visitor authentication.
+
+## Installation
+
+```bash
+yarn add @jay-framework/wix-server-client
+```
+
+## Configuration
+
+Create a configuration file at `./config/.wix.yaml` relative to your process execution path:
+
+```yaml
+# Server-side API Key authentication (required)
+apiKeyStrategy:
+  apiKey: 'your-api-key-here'
+  siteId: 'your-site-id-here'
+
+# Client-side OAuth authentication (optional)
+# Enables direct API calls from the browser
+oauthStrategy:
+  clientId: 'your-oauth-client-id-here'
+```
+
+### Configuration Fields
+
+**apiKeyStrategy** (required):
+
+- `apiKey`: Your Wix API key (string, required)
+- `siteId`: Your Wix site ID (string, required)
+
+**oauthStrategy** (optional):
+
+- `clientId`: OAuth client ID for visitor authentication
+
+## Server-Side Usage
+
+```typescript
+import { getWixClient } from '@jay-framework/wix-server-client';
+import { products } from '@wix/stores';
+
+// Get the API Key authenticated client
+const wixClient = getWixClient();
+
+// Make server-side API calls
+const productsClient = wixClient.use(products);
+const myProducts = await productsClient.queryProducts().find();
+```
+
+## Client-Side OAuth Authentication
+
+When `oauthStrategy.clientId` is configured, the plugin enables client-side API calls using OAuth visitor tokens. This is useful for:
+
+- Add to cart without server round-trip
+- Real-time search autocomplete
+- Client-side cart management
+
+### How It Works
+
+Based on the [Wix Headless Visitor Authentication Guide](https://dev.wix.com/docs/go-headless/develop-your-project/self-managed-headless/authentication/visitors/handle-visitors-using-the-js-sdk):
+
+1. **Server Init**: Passes OAuth `clientId` to the client via `setClientInitData`
+2. **Client Init**: Creates an OAuth-authenticated Wix client
+3. **Token Management**: Visitor tokens are stored in `localStorage` for session persistence
+4. **Session Resume**: On page reload, existing tokens are used to resume the visitor session
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    SERVER (lib/init.ts - withServer)                 │
+├─────────────────────────────────────────────────────────────────────┤
+│  Config: oauthStrategy.clientId = "abc123"                          │
+│  return { oauthClientId: "abc123" }  // typed data for client       │
+└─────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼ (embedded in HTML)
+┌─────────────────────────────────────────────────────────────────────┐
+│                    CLIENT (lib/init.ts - withClient)                 │
+├─────────────────────────────────────────────────────────────────────┤
+│  1. Receive typed data from withServer                              │
+│  2. Check localStorage for existing tokens                          │
+│  3. Create OAuthStrategy client with clientId                       │
+│  4. If no tokens: generateVisitorTokens() and store                 │
+│  5. If tokens exist: validate/refresh and resume session            │
+│  6. Register WIX_CLIENT_CONTEXT for component access                │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Using the Client in Components
+
+```typescript
+import { useContext } from '@jay-framework/runtime';
+import { WIX_CLIENT_CONTEXT } from '@jay-framework/wix-server-client';
+
+// In your interactive component
+function MyComponent(props, refs) {
+  const wixClient = useContext(WIX_CLIENT_CONTEXT);
+
+  if (wixClient.isReady) {
+    // Make client-side API calls
+    const tokens = wixClient.getTokens();
+    console.log('Visitor session active');
+  }
+}
+```
+
+### Token Storage
+
+Tokens are automatically stored in `localStorage` under the key `wix_visitor_tokens`:
+
+```typescript
+// Clear tokens (for logout or session reset)
+import { clearStoredTokens } from '@jay-framework/wix-server-client';
+
+clearStoredTokens();
+```
+
+## Plugin Initialization
+
+This package uses the `makeJayInit` pattern for consolidated server/client initialization:
+
+### lib/init.ts
+
+```typescript
+import { makeJayInit } from '@jay-framework/fullstack-component';
+import { loadConfig } from './config-loader.js';
+import { registerGlobalContext } from '@jay-framework/runtime';
+
+export const init = makeJayInit()
+  .withServer(async () => {
+    const config = loadConfig();
+
+    // Pass OAuth client ID to client for visitor authentication
+    return {
+      oauthClientId: config.oauth?.clientId || null,
+    };
+  })
+  .withClient(async (data) => {
+    // Set up OAuth-authenticated Wix client
+    // Token management with localStorage
+    registerGlobalContext(WIX_CLIENT_CONTEXT, clientContext);
+  });
+```
+
+### Initialization Order
+
+1. `wix-server-client` must initialize before `wix-stores`
+2. Add `wix-server-client` as a dependency in your project's `package.json`
+3. Plugin dependencies in `package.json` determine initialization order
+
+## API Reference
+
+### Server-Side
+
+#### `getWixClient(): WixClient`
+
+Returns a server-side Wix client authenticated with API Key.
+
+#### `getOAuthClientId(): string | undefined`
+
+Returns the OAuth client ID from config, or undefined if not configured.
+
+#### `loadConfig(): WixConfig`
+
+Loads and validates the configuration from `./config/.wix.yaml`.
+
+### Client-Side
+
+#### `WIX_CLIENT_CONTEXT`
+
+Context marker for accessing the Wix client in components.
+
+```typescript
+interface WixClientContext {
+  client: WixClient | null;
+  isReady: boolean;
+  getTokens(): Tokens | null;
+  generateVisitorTokens(): Promise<Tokens>;
+  refreshToken(): Promise<Tokens>;
+}
+```
+
+#### `getWixClientInstance(): WixClient | null`
+
+Get the global Wix client instance for imperative access.
+
+#### `clearStoredTokens(): void`
+
+Clear stored visitor tokens from localStorage.
+
+## Error Handling
+
+The `loadConfig()` function will throw descriptive errors if:
+
+- The config file is not found at `./config/.wix.yaml`
+- The YAML syntax is invalid
+- Required fields (`apiKey`, `siteId`) are missing
+- Required fields are empty strings
+
+## License
+
+Apache-2.0

package/dist/index.client.js

@@ -0,0 +1,73 @@
+import { createJayContext, registerGlobalContext } from "@jay-framework/runtime";
+import { createClient, OAuthStrategy } from "@wix/sdk";
+import { makeJayInit } from "@jay-framework/fullstack-component";
+const WIX_CLIENT_CONTEXT = createJayContext();
+const TOKENS_STORAGE_KEY = "wix_visitor_tokens";
+function storeTokens(tokens, oauthClientId) {
+  try {
+    localStorage.setItem(
+      TOKENS_STORAGE_KEY + oauthClientId,
+      JSON.stringify({ tokens, oauthClientId })
+    );
+  } catch (error) {
+    console.warn("[WixClient] Failed to store tokens:", error);
+  }
+}
+function getStoredTokens(oauthClientId) {
+  try {
+    const stored = localStorage.getItem(TOKENS_STORAGE_KEY + oauthClientId);
+    if (stored) {
+      return JSON.parse(stored);
+    }
+  } catch (error) {
+    console.warn("[WixClient] Failed to retrieve tokens:", error);
+  }
+  return null;
+}
+async function provideWixClientContext(oauthClientId) {
+  const storedTokens = getStoredTokens(oauthClientId);
+  console.log("[wix-server-client] createClient with tokens: ", void 0);
+  const wixClient = createClient({
+    auth: OAuthStrategy({
+      clientId: oauthClientId,
+      tokens: storedTokens?.oauthClientId === oauthClientId ? storedTokens.tokens : void 0
+    })
+  });
+  if (!storedTokens || !storedTokens?.oauthClientId) {
+    const tokens = await wixClient.auth.generateVisitorTokens();
+    wixClient.auth.setTokens(tokens);
+    storeTokens(tokens, oauthClientId);
+  }
+  const clientContext = {
+    client: wixClient,
+    isReady: true,
+    getTokens() {
+      return wixClient.auth.getTokens();
+    },
+    async generateVisitorTokens() {
+      const tokens = await wixClient.auth.generateVisitorTokens();
+      storeTokens(tokens, oauthClientId);
+      return tokens;
+    },
+    async refreshToken() {
+      const currentTokens = wixClient.auth.getTokens();
+      if (!currentTokens?.refreshToken) {
+        throw new Error("No refresh token available");
+      }
+      const tokens = await wixClient.auth.renewToken(currentTokens.refreshToken);
+      storeTokens(tokens, oauthClientId);
+      return tokens;
+    }
+  };
+  registerGlobalContext(WIX_CLIENT_CONTEXT, clientContext);
+}
+const init = makeJayInit().withClient(async (data) => {
+  console.log("[wix-server-client] Initializing client-side Wix client...");
+  const { oauthClientId } = data;
+  await provideWixClientContext(oauthClientId);
+  console.log("[wix-server-client] Client initialization complete");
+});
+export {
+  WIX_CLIENT_CONTEXT,
+  init
+};

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import * as _jay_framework_fullstack_component from '@jay-framework/fullstack-component';
+import { WixClient, Tokens } from '@wix/sdk';
+import * as _jay_framework_runtime from '@jay-framework/runtime';
+import { PluginSetupContext, PluginSetupResult } from '@jay-framework/stack-server-runtime';
+
+/**
+ * Configuration for API Key authentication (server-side)
+ */
+interface ApiKeyConfig {
+    apiKey: string;
+    siteId: string;
+}
+/**
+ * Configuration for OAuth authentication (client-side)
+ */
+interface OAuthConfig {
+    clientId: string;
+}
+/**
+ * Full Wix configuration
+ */
+interface WixConfig {
+    /** API Key strategy for server-side auth (required) */
+    apiKey: ApiKeyConfig;
+    /** OAuth strategy for client-side auth (optional) */
+    oauth: OAuthConfig;
+}
+declare function loadConfig(): WixConfig;
+
+interface WixClientService {
+    wixClient: WixClient;
+}
+declare const WIX_CLIENT_SERVICE: _jay_framework_fullstack_component.ServiceMarker<WixClientService>;
+
+interface WixClientContext {
+    /** The Wix SDK client (null if OAuth not configured) */
+    client: WixClient | null;
+    /** Whether the client is ready for use */
+    isReady: boolean;
+    /** Get current tokens */
+    getTokens(): Tokens | null;
+    /** Generate new visitor tokens (creates new session) */
+    generateVisitorTokens(): Promise<Tokens>;
+    /** Refresh the access token using the refresh token */
+    refreshToken(): Promise<Tokens>;
+}
+declare const WIX_CLIENT_CONTEXT: _jay_framework_runtime.ContextMarker<WixClientContext>;
+
+declare const init: _jay_framework_fullstack_component.JayInit<{
+    oauthClientId: string;
+}>;
+
+/**
+ * Setup handler for wix-server-client plugin (Design Log #87).
+ *
+ * Creates config/.wix.yaml template if missing, validates credentials.
+ * No reference data (credentials-only plugin).
+ */
+
+declare function setupWixServerClient(ctx: PluginSetupContext): Promise<PluginSetupResult>;
+
+export { type ApiKeyConfig, type OAuthConfig, WIX_CLIENT_CONTEXT, WIX_CLIENT_SERVICE, type WixClientContext, type WixClientService, type WixConfig, init, loadConfig, setupWixServerClient };

package/dist/index.js

@@ -0,0 +1,153 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { createClient, ApiKeyStrategy } from "@wix/sdk";
+import { createJayService, makeJayInit } from "@jay-framework/fullstack-component";
+import { registerService } from "@jay-framework/stack-server-runtime";
+import { createJayContext } from "@jay-framework/runtime";
+function loadConfig() {
+  const configPath = path.join(process.cwd(), "config", ".wix.yaml");
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Config file not found at: ${configPath}`);
+  }
+  const fileContents = fs.readFileSync(configPath, "utf8");
+  const config = yaml.load(fileContents);
+  if (!config) {
+    throw new Error("Config file is empty or invalid");
+  }
+  if (!config.apiKeyStrategy) {
+    throw new Error('Config validation failed: "apiKeyStrategy" section is required');
+  }
+  const strategy = config.apiKeyStrategy;
+  if (!strategy.apiKey) {
+    throw new Error('Config validation failed: "apiKeyStrategy.apiKey" is required');
+  }
+  if (typeof strategy.apiKey !== "string" || strategy.apiKey.trim() === "") {
+    throw new Error(
+      'Config validation failed: "apiKeyStrategy.apiKey" must be a non-empty string'
+    );
+  }
+  if (!strategy.siteId) {
+    throw new Error('Config validation failed: "apiKeyStrategy.siteId" is required');
+  }
+  if (typeof strategy.siteId !== "string" || strategy.siteId.trim() === "") {
+    throw new Error(
+      'Config validation failed: "apiKeyStrategy.siteId" must be a non-empty string'
+    );
+  }
+  if (!config.oauthStrategy) {
+    throw new Error('Config validation failed: "oauthStrategy" section is required');
+  }
+  const oauth = config.oauthStrategy;
+  if (!oauth.clientId || typeof oauth.clientId !== "string" || oauth.clientId.trim() === "") {
+    throw new Error(
+      'Config validation failed: "oauthStrategy.clientId" must be a non-empty string'
+    );
+  }
+  return {
+    apiKey: {
+      apiKey: strategy.apiKey,
+      siteId: strategy.siteId
+    },
+    oauth: {
+      clientId: oauth.clientId
+    }
+  };
+}
+const WIX_CLIENT_SERVICE = createJayService("WixClientService");
+function provideWixClientService(config) {
+  const instance = createClient({
+    auth: ApiKeyStrategy({
+      apiKey: config.apiKey.apiKey,
+      siteId: config.apiKey.siteId
+    }),
+    modules: {}
+  });
+  registerService(WIX_CLIENT_SERVICE, instance);
+}
+const WIX_CLIENT_CONTEXT = createJayContext();
+const init = makeJayInit().withServer(async () => {
+  console.log("[wix-server-client] Initializing Wix client configuration...");
+  const config = loadConfig();
+  provideWixClientService(config);
+  return {
+    oauthClientId: config.oauth.clientId
+  };
+});
+const CONFIG_FILE_NAME = ".wix.yaml";
+const CONFIG_TEMPLATE = `# Wix API Configuration
+# 
+# This file contains credentials for connecting to your Wix site.
+# Get these values from your Wix dashboard:
+#   - API Key: https://dev.wix.com/docs/rest/articles/getting-started/api-keys
+#   - Site ID: Found in your Wix dashboard URL or site settings
+#   - OAuth Client ID: Create an OAuth app in Wix Developers dashboard
+#
+# IMPORTANT: This file contains secrets. Add config/.wix.yaml to .gitignore.
+
+# Server-side authentication (required)
+apiKeyStrategy:
+  apiKey: "<your-api-key>"
+  siteId: "<your-site-id>"
+
+# Client-side authentication (required for interactive features)
+oauthStrategy:
+  clientId: "<your-oauth-client-id>"
+`;
+async function setupWixServerClient(ctx) {
+  const configPath = path.join(ctx.configDir, CONFIG_FILE_NAME);
+  if (!fs.existsSync(configPath)) {
+    if (!fs.existsSync(ctx.configDir)) {
+      fs.mkdirSync(ctx.configDir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, CONFIG_TEMPLATE, "utf-8");
+    return {
+      status: "needs-config",
+      configCreated: [`config/${CONFIG_FILE_NAME}`],
+      message: "Fill in your Wix API credentials and re-run: jay-stack setup wix-server-client"
+    };
+  }
+  try {
+    const configContent = fs.readFileSync(configPath, "utf-8");
+    const config = yaml.load(configContent);
+    if (!config) {
+      return {
+        status: "error",
+        message: `Config file is empty: config/${CONFIG_FILE_NAME}`
+      };
+    }
+    const apiKey = config.apiKeyStrategy?.apiKey || "";
+    const siteId = config.apiKeyStrategy?.siteId || "";
+    const clientId = config.oauthStrategy?.clientId || "";
+    const hasPlaceholders = apiKey.startsWith("<") || siteId.startsWith("<") || clientId.startsWith("<");
+    const isEmpty = !apiKey || !siteId;
+    if (hasPlaceholders || isEmpty) {
+      return {
+        status: "needs-config",
+        message: `Config has placeholder values. Fill in credentials in config/${CONFIG_FILE_NAME}`
+      };
+    }
+    if (ctx.initError) {
+      return {
+        status: "error",
+        message: `Credentials invalid or connection failed: ${ctx.initError.message}`
+      };
+    }
+    return {
+      status: "configured",
+      message: `Wix client connected (site: ${siteId.substring(0, 8)}...)`
+    };
+  } catch (error) {
+    return {
+      status: "error",
+      message: `Failed to read config: ${error.message}`
+    };
+  }
+}
+export {
+  WIX_CLIENT_CONTEXT,
+  WIX_CLIENT_SERVICE,
+  init,
+  loadConfig,
+  setupWixServerClient
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@jay-framework/wix-server-client",
+  "version": "0.15.0",
+  "type": "module",
+  "description": "Wix SDK client configuration and authentication for Jay Framework",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "plugin.yaml"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/index.client.js",
+    "./plugin.yaml": "./plugin.yaml"
+  },
+  "scripts": {
+    "build": "npm run clean && npm run build:client && npm run build:server && npm run build:types",
+    "build:client": "vite build",
+    "build:server": "vite build --ssr",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run test",
+    "test": ":"
+  },
+  "dependencies": {
+    "@jay-framework/component": "^0.14.0",
+    "@jay-framework/fullstack-component": "^0.14.0",
+    "@jay-framework/reactive": "^0.14.0",
+    "@jay-framework/runtime": "^0.14.0",
+    "@jay-framework/secure": "^0.14.0",
+    "@jay-framework/stack-client-runtime": "^0.14.0",
+    "@jay-framework/stack-server-runtime": "^0.14.0",
+    "@wix/sdk": "^1.21.5",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.7",
+    "@babel/preset-env": "^7.23.8",
+    "@babel/preset-typescript": "^7.23.3",
+    "@jay-framework/compiler-jay-stack": "^0.14.0",
+    "@jay-framework/jay-cli": "^0.14.0",
+    "@jay-framework/vite-plugin": "^0.14.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "nodemon": "^3.0.3",
+    "rimraf": "^5.0.5",
+    "tslib": "^2.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vite-plugin-inspect": "^0.8.1"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,9 @@
+name: wix-server-client
+# Wix SDK client configuration and authentication
+
+# Plugin initialization uses makeJayInit pattern in lib/init.ts
+# Export name defaults to 'init'
+
+setup:
+  handler: setupWixServerClient
+  description: Configure Wix API credentials (API key, site ID, OAuth client ID)