@hasna/connectors 1.3.43 → 1.3.45

package/connectors/walmart-marketplace/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+Guidance for AI agents working with the Walmart Marketplace connector.
+
+## Overview
+
+`@hasna/connect-walmart-marketplace` wraps the Walmart Marketplace REST API v3 for items, inventory, and orders.
+
+## Authentication
+
+API Key / OAuth token auth via `WM_SEC.ACCESS_TOKEN`. Users must also configure `WM_SVC.NAME` (`WALMART_SERVICE_NAME`). Correlation IDs default to `crypto.randomUUID()` per request unless overridden.
+
+## Security
+
+- No hardcoded tokens or secrets
+- `.env.example` has placeholders only
+- No `browser-use` dependency
+- No internal references (`beepmedia`, `hasnaxyz`)
+
+## Adding Endpoints
+
+1. Add types in `src/types/index.ts`
+2. Add API module in `src/api/`
+3. Wire in `src/api/index.ts`
+4. Add CLI commands in `src/cli/index.ts`
+5. Add tests with mocked `fetch`

package/connectors/walmart-marketplace/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md
+
+Walmart Marketplace API connector (`@hasna/connect-walmart-marketplace`).
+
+## Commands
+
+```bash
+bun install
+bun run dev
+bun run build
+bun run typecheck
+bun test
+```
+
+## API
+
+- Base URL: `https://marketplace.walmartapis.com/v3`
+- Auth: OAuth access token in `WM_SEC.ACCESS_TOKEN`
+- Required headers: `WM_SEC.ACCESS_TOKEN`, `WM_QOS.CORRELATION_ID`, `WM_SVC.NAME`
+- Resources: items (`/items`), inventory (`/inventory`), orders (`/orders`)
+
+## Configuration
+
+Profiles at `~/.hasna/connectors/connect-walmart-marketplace/`.
+
+Environment variables: `WALMART_ACCESS_TOKEN`, `WALMART_SERVICE_NAME`, optional `WALMART_BASE_URL`, `WALMART_CORRELATION_ID`.
+
+`serviceName` must be set by the user (no internal brand defaults).
+
+## Structure
+
+```
+src/api/client.ts      # HTTP client with WM_* headers
+src/api/items.ts       # Items API
+src/api/inventory.ts   # Inventory API
+src/api/orders.ts      # Orders API
+src/cli/index.ts       # Commander CLI
+src/utils/config.ts    # Multi-profile config
+```

package/connectors/walmart-marketplace/README.md

@@ -0,0 +1,67 @@
+# connect-walmart-marketplace
+
+TypeScript connector for the [Walmart Marketplace API v3](https://developer.walmart.com/). Manage items, inventory, and orders with a CLI and programmatic API.
+
+## Features
+
+- OAuth access token authentication (`WM_SEC.ACCESS_TOKEN`)
+- Required `WM_SVC.NAME` and `WM_QOS.CORRELATION_ID` headers per Walmart API spec
+- Multi-profile configuration
+- Items, inventory, and orders list/get commands
+- JSON and pretty output formats
+
+## Quick Start
+
+```bash
+cd connectors/walmart-marketplace
+bun install
+bun run dev config set-token <access-token>
+bun run dev config set-service-name <your-wm-svc-name>
+bun run dev items list
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WALMART_ACCESS_TOKEN` | OAuth access token from Walmart Token API |
+| `WALMART_SERVICE_NAME` | Value for `WM_SVC.NAME` header |
+| `WALMART_BASE_URL` | Optional API base URL (default: `https://marketplace.walmartapis.com/v3`) |
+| `WALMART_CORRELATION_ID` | Optional default correlation ID (auto-generated per request if unset) |
+
+Copy `.env.example` for local development placeholders only — never commit real credentials.
+
+## CLI Commands
+
+```bash
+connect-walmart-marketplace items list [--limit N]
+connect-walmart-marketplace items get <sku>
+connect-walmart-marketplace inventory list [--sku <sku>]
+connect-walmart-marketplace inventory get <sku>
+connect-walmart-marketplace orders list [--limit N]
+connect-walmart-marketplace orders get <purchaseOrderId>
+connect-walmart-marketplace profile list|use|create|delete|show
+connect-walmart-marketplace config set-token|set-service-name|show|clear
+```
+
+## Programmatic Usage
+
+```typescript
+import { WalmartMarketplace } from '@hasna/connect-walmart-marketplace';
+
+const walmart = new WalmartMarketplace({
+  accessToken: process.env.WALMART_ACCESS_TOKEN!,
+  serviceName: process.env.WALMART_SERVICE_NAME!,
+});
+
+const items = await walmart.items.list({ limit: 20 });
+const order = await walmart.orders.get('123456789');
+```
+
+## Configuration Storage
+
+Profiles are stored at `~/.hasna/connectors/connect-walmart-marketplace/profiles/`.
+
+## License
+
+Apache-2.0

package/connectors/walmart-marketplace/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hasna/connect-walmart-marketplace",
+  "version": "0.0.1",
+  "description": "Walmart Marketplace API connector - Items, inventory, and orders",
+  "type": "module",
+  "bin": {
+    "connect-walmart-marketplace": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "walmart",
+    "marketplace",
+    "ecommerce",
+    "orders",
+    "inventory",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/open-connectors.git"
+  }
+}

package/connectors/walmart-marketplace/src/api/client.ts

@@ -0,0 +1,132 @@
+import type { WalmartMarketplaceConfig } from '../types';
+import { WalmartMarketplaceApiError } from '../types';
+
+export const DEFAULT_BASE_URL = 'https://marketplace.walmartapis.com/v3';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+  correlationId?: string;
+}
+
+export class WalmartMarketplaceClient {
+  private readonly accessToken: string;
+  private readonly serviceName: string;
+  private readonly baseUrl: string;
+  private readonly defaultCorrelationId?: string;
+
+  constructor(config: WalmartMarketplaceConfig) {
+    if (!config.accessToken) {
+      throw new Error('Access token is required');
+    }
+    if (!config.serviceName) {
+      throw new Error('Service name is required');
+    }
+
+    this.accessToken = config.accessToken;
+    this.serviceName = config.serviceName;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.defaultCorrelationId = config.correlationId;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  private resolveCorrelationId(override?: string): string {
+    return override || this.defaultCorrelationId || crypto.randomUUID();
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, correlationId } = options;
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'WM_SEC.ACCESS_TOKEN': this.accessToken,
+      'WM_QOS.CORRELATION_ID': this.resolveCorrelationId(correlationId),
+      'WM_SVC.NAME': this.serviceName,
+      ...headers,
+    };
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const errorData = data as { errors?: Array<{ description?: string; info?: string }> };
+      const firstError = errorData?.errors?.[0];
+      throw new WalmartMarketplaceApiError(
+        firstError?.description || firstError?.info || `Walmart Marketplace API error: ${response.status}`,
+        response.status,
+        errorData?.errors
+      );
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, options?: Pick<RequestOptions, 'correlationId'>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params, ...options });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown>, params });
+  }
+
+  getAccessTokenPreview(): string {
+    if (this.accessToken.length > 10) {
+      return `${this.accessToken.substring(0, 6)}...${this.accessToken.substring(this.accessToken.length - 4)}`;
+    }
+    return '***';
+  }
+
+  getServiceName(): string {
+    return this.serviceName;
+  }
+}

package/connectors/walmart-marketplace/src/api/index.ts

@@ -0,0 +1,53 @@
+import type { WalmartMarketplaceConfig } from '../types';
+import { WalmartMarketplaceClient } from './client';
+import { ItemsApi } from './items';
+import { InventoryApi } from './inventory';
+import { OrdersApi } from './orders';
+
+export class WalmartMarketplace {
+  private readonly client: WalmartMarketplaceClient;
+
+  public readonly items: ItemsApi;
+  public readonly inventory: InventoryApi;
+  public readonly orders: OrdersApi;
+
+  constructor(config: WalmartMarketplaceConfig) {
+    this.client = new WalmartMarketplaceClient(config);
+    this.items = new ItemsApi(this.client);
+    this.inventory = new InventoryApi(this.client);
+    this.orders = new OrdersApi(this.client);
+  }
+
+  static fromEnv(): WalmartMarketplace {
+    const accessToken = process.env.WALMART_ACCESS_TOKEN;
+    const serviceName = process.env.WALMART_SERVICE_NAME;
+    const baseUrl = process.env.WALMART_BASE_URL;
+    const correlationId = process.env.WALMART_CORRELATION_ID;
+
+    if (!accessToken) {
+      throw new Error('WALMART_ACCESS_TOKEN environment variable is required');
+    }
+    if (!serviceName) {
+      throw new Error('WALMART_SERVICE_NAME environment variable is required');
+    }
+
+    return new WalmartMarketplace({ accessToken, serviceName, baseUrl, correlationId });
+  }
+
+  getAccessTokenPreview(): string {
+    return this.client.getAccessTokenPreview();
+  }
+
+  getServiceName(): string {
+    return this.client.getServiceName();
+  }
+
+  getClient(): WalmartMarketplaceClient {
+    return this.client;
+  }
+}
+
+export { WalmartMarketplaceClient, DEFAULT_BASE_URL } from './client';
+export { ItemsApi } from './items';
+export { InventoryApi } from './inventory';
+export { OrdersApi } from './orders';

package/connectors/walmart-marketplace/src/api/inventory.ts

@@ -0,0 +1,30 @@
+import type { WalmartMarketplaceClient } from './client';
+import type { WalmartInventoryListResponse } from '../types';
+
+export interface ListInventoryOptions {
+  limit?: number;
+  offset?: number;
+  sku?: string;
+  shipNode?: string;
+}
+
+export class InventoryApi {
+  constructor(private readonly client: WalmartMarketplaceClient) {}
+
+  async list(options: ListInventoryOptions = {}): Promise<WalmartInventoryListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {};
+
+    if (options.limit !== undefined) params.limit = options.limit;
+    if (options.offset !== undefined) params.offset = options.offset;
+    if (options.sku) params.sku = options.sku;
+    if (options.shipNode) params.shipNode = options.shipNode;
+
+    return this.client.get<WalmartInventoryListResponse>('/inventory', params);
+  }
+
+  async get(sku: string, shipNode?: string): Promise<WalmartInventoryListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = { sku };
+    if (shipNode) params.shipNode = shipNode;
+    return this.client.get<WalmartInventoryListResponse>('/inventory', params);
+  }
+}

package/connectors/walmart-marketplace/src/api/items.ts

@@ -0,0 +1,37 @@
+import type { WalmartMarketplaceClient } from './client';
+import type { WalmartItem, WalmartItemsListResponse, WalmartItemResponse } from '../types';
+
+export interface ListItemsOptions {
+  limit?: number;
+  offset?: number;
+  sku?: string;
+  lifecycleStatus?: string;
+  publishedStatus?: string;
+  nextCursor?: string;
+}
+
+export class ItemsApi {
+  constructor(private readonly client: WalmartMarketplaceClient) {}
+
+  async list(options: ListItemsOptions = {}): Promise<WalmartItemsListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {};
+
+    if (options.limit !== undefined) params.limit = options.limit;
+    if (options.offset !== undefined) params.offset = options.offset;
+    if (options.sku) params.sku = options.sku;
+    if (options.lifecycleStatus) params.lifecycleStatus = options.lifecycleStatus;
+    if (options.publishedStatus) params.publishedStatus = options.publishedStatus;
+    if (options.nextCursor) params.nextCursor = options.nextCursor;
+
+    return this.client.get<WalmartItemsListResponse>('/items', params);
+  }
+
+  async get(sku: string): Promise<WalmartItem> {
+    const response = await this.client.get<WalmartItemResponse>(`/items/${encodeURIComponent(sku)}`);
+    const item = response.ItemResponse?.[0];
+    if (!item) {
+      throw new Error(`Item not found for SKU: ${sku}`);
+    }
+    return item;
+  }
+}

package/connectors/walmart-marketplace/src/api/orders.ts

@@ -0,0 +1,44 @@
+import type { WalmartMarketplaceClient } from './client';
+import type { WalmartOrder, WalmartOrdersListResponse, WalmartOrderResponse } from '../types';
+
+export interface ListOrdersOptions {
+  limit?: number;
+  offset?: number;
+  createdStartDate?: string;
+  createdEndDate?: string;
+  shipNodeType?: 'SellerFulfilled' | 'WFSFulfilled' | '3PLFulfilled';
+  productInfo?: boolean;
+  replacementInfo?: boolean;
+  incentiveInfo?: boolean;
+  nextCursor?: string;
+}
+
+export class OrdersApi {
+  constructor(private readonly client: WalmartMarketplaceClient) {}
+
+  async list(options: ListOrdersOptions = {}): Promise<WalmartOrdersListResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {};
+
+    if (options.limit !== undefined) params.limit = options.limit;
+    if (options.offset !== undefined) params.offset = options.offset;
+    if (options.createdStartDate) params.createdStartDate = options.createdStartDate;
+    if (options.createdEndDate) params.createdEndDate = options.createdEndDate;
+    if (options.shipNodeType) params.shipNodeType = options.shipNodeType;
+    if (options.productInfo !== undefined) params.productInfo = options.productInfo;
+    if (options.replacementInfo !== undefined) params.replacementInfo = options.replacementInfo;
+    if (options.incentiveInfo !== undefined) params.incentiveInfo = options.incentiveInfo;
+    if (options.nextCursor) params.nextCursor = options.nextCursor;
+
+    return this.client.get<WalmartOrdersListResponse>('/orders', params);
+  }
+
+  async get(purchaseOrderId: string): Promise<WalmartOrder> {
+    const response = await this.client.get<WalmartOrderResponse>(
+      `/orders/${encodeURIComponent(purchaseOrderId)}`
+    );
+    if (!response.order) {
+      throw new Error(`Order not found: ${purchaseOrderId}`);
+    }
+    return response.order;
+  }
+}

package/connectors/walmart-marketplace/src/api/walmart-marketplace.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, mock } from 'bun:test';
+import { WalmartMarketplace } from './index';
+import { WalmartMarketplaceClient, DEFAULT_BASE_URL } from './client';
+import { ItemsApi } from './items';
+
+describe('WalmartMarketplaceClient', () => {
+  it('requires access token and service name', () => {
+    expect(() => new WalmartMarketplaceClient({ accessToken: '', serviceName: 'svc' })).toThrow(
+      'Access token is required'
+    );
+    expect(() => new WalmartMarketplaceClient({ accessToken: 'token', serviceName: '' })).toThrow(
+      'Service name is required'
+    );
+  });
+
+  it('includes WM_SEC.ACCESS_TOKEN and WM_SVC.NAME headers on GET /items', async () => {
+    const originalFetch = globalThis.fetch;
+    let capturedUrl = '';
+    let capturedHeaders: Record<string, string> = {};
+
+    globalThis.fetch = mock((_url: unknown, options: { headers: Record<string, string> }) => {
+      capturedUrl = String(_url);
+      capturedHeaders = options.headers;
+      return Promise.resolve(
+        new Response(JSON.stringify({ ItemResponse: [], totalItems: 0 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      );
+    }) as any;
+
+    const client = new WalmartMarketplaceClient({
+      accessToken: 'test-access-token',
+      serviceName: 'Test Marketplace Service',
+      correlationId: 'fixed-correlation-id',
+    });
+
+    await client.get('/items');
+
+    expect(capturedUrl).toBe(`${DEFAULT_BASE_URL}/items`);
+    expect(capturedHeaders['WM_SEC.ACCESS_TOKEN']).toBe('test-access-token');
+    expect(capturedHeaders['WM_SVC.NAME']).toBe('Test Marketplace Service');
+    expect(capturedHeaders['WM_QOS.CORRELATION_ID']).toBe('fixed-correlation-id');
+    expect(capturedHeaders['Accept']).toBe('application/json');
+
+    globalThis.fetch = originalFetch;
+  });
+});
+
+describe('ItemsApi', () => {
+  it('list-items builds GET https://marketplace.walmartapis.com/v3/items with required headers', async () => {
+    const originalFetch = globalThis.fetch;
+    let capturedUrl = '';
+    let capturedMethod = '';
+    let capturedHeaders: Record<string, string> = {};
+
+    globalThis.fetch = mock((_url: unknown, options: { method: string; headers: Record<string, string> }) => {
+      capturedUrl = String(_url);
+      capturedMethod = options.method;
+      capturedHeaders = options.headers;
+      return Promise.resolve(
+        new Response(JSON.stringify({ ItemResponse: [{ sku: 'SKU-1' }], totalItems: 1 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      );
+    }) as any;
+
+    const marketplace = new WalmartMarketplace({
+      accessToken: 'wm-token-123',
+      serviceName: 'My Walmart App',
+    });
+
+    const result = await marketplace.items.list({ limit: 20 });
+
+    expect(capturedMethod).toBe('GET');
+    expect(capturedUrl).toBe('https://marketplace.walmartapis.com/v3/items?limit=20');
+    expect(capturedHeaders['WM_SEC.ACCESS_TOKEN']).toBe('wm-token-123');
+    expect(capturedHeaders['WM_SVC.NAME']).toBe('My Walmart App');
+    expect(capturedHeaders['WM_QOS.CORRELATION_ID']).toBeTruthy();
+    expect(result.ItemResponse).toHaveLength(1);
+
+    globalThis.fetch = originalFetch;
+  });
+
+  it('get item by SKU encodes path segment', async () => {
+    const originalFetch = globalThis.fetch;
+    let capturedUrl = '';
+
+    globalThis.fetch = mock((url: unknown) => {
+      capturedUrl = String(url);
+      return Promise.resolve(
+        new Response(JSON.stringify({ ItemResponse: [{ sku: 'SKU/ABC' }] }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        })
+      );
+    }) as any;
+
+    const api = new ItemsApi(
+      new WalmartMarketplaceClient({
+        accessToken: 'token',
+        serviceName: 'svc',
+      })
+    );
+
+    await api.get('SKU/ABC');
+    expect(capturedUrl).toContain('/items/SKU%2FABC');
+
+    globalThis.fetch = originalFetch;
+  });
+});
+
+describe('WalmartMarketplace', () => {
+  it('creates from environment variables', () => {
+    const prevToken = process.env.WALMART_ACCESS_TOKEN;
+    const prevService = process.env.WALMART_SERVICE_NAME;
+
+    process.env.WALMART_ACCESS_TOKEN = 'env-token';
+    process.env.WALMART_SERVICE_NAME = 'env-service';
+
+    const marketplace = WalmartMarketplace.fromEnv();
+    expect(marketplace.getServiceName()).toBe('env-service');
+
+    if (prevToken) process.env.WALMART_ACCESS_TOKEN = prevToken;
+    else delete process.env.WALMART_ACCESS_TOKEN;
+    if (prevService) process.env.WALMART_SERVICE_NAME = prevService;
+    else delete process.env.WALMART_SERVICE_NAME;
+  });
+
+  it('throws when env credentials are missing', () => {
+    const prevToken = process.env.WALMART_ACCESS_TOKEN;
+    const prevService = process.env.WALMART_SERVICE_NAME;
+    delete process.env.WALMART_ACCESS_TOKEN;
+    delete process.env.WALMART_SERVICE_NAME;
+
+    expect(() => WalmartMarketplace.fromEnv()).toThrow('WALMART_ACCESS_TOKEN');
+
+    process.env.WALMART_ACCESS_TOKEN = 'token';
+    expect(() => WalmartMarketplace.fromEnv()).toThrow('WALMART_SERVICE_NAME');
+
+    if (prevToken) process.env.WALMART_ACCESS_TOKEN = prevToken;
+    else delete process.env.WALMART_ACCESS_TOKEN;
+    if (prevService) process.env.WALMART_SERVICE_NAME = prevService;
+    else delete process.env.WALMART_SERVICE_NAME;
+  });
+});