Shops

A Shop is one user-owned order source. A ShopPlatform describes how Openship searches that source's products and orders, retrieves one product, updates product data, and manages source webhooks. The platform is reusable configuration; the shop holds the connection-specific domain and credentials.

Current model boundary

Shop belongs directly to one Openship user and references one ShopPlatform. It stores the source name, domain, access/refresh token fields, token expiry, metadata, orders, links, and shop items. ShopPlatform stores the operation selectors and OAuth configuration used by its shops.

Openship is user-scoped rather than organization- or workspace-scoped. Every query and command must verify that the acting session or API key owns the selected shop and any related order, link, match, or item. Regions, channels, and provider domains do not create a separate tenant boundary.

The current token fields are ordinary model text fields and do not establish encrypted secret storage or field-read denial. Treat the source as requiring a credential-storage review before connecting a real store.

Compiled adapters

Current files under features/integrations/shop provide:

• shopify.ts for Shopify product/order operations;
• openfront.ts for the Openfront GraphQL contract;
• lib/executor.ts for dispatching the selected operation.

The adapter shape includes product search/detail, order search, product update, and webhook operations. Handler support varies; an operation appearing in GraphQL or a platform row does not prove that both compiled adapters implement the same effect.

The executor also accepts database-selected HTTP URLs and dynamic function paths. That is an extension mechanism, not an allowlist. Before enabling custom execution, restrict schemes and destinations, block private/network metadata addresses, disable redirects, bound time and response size, validate response schemas, isolate credentials, and record retries and reconciliation.

Operator workflow

1. Initialize the first user at /dashboard/init and sign in.
2. Open /dashboard/platform/shops.
3. Create or inspect a ShopPlatform whose operation selectors match an implemented adapter.
4. Create a Shop owned by the current user and attach only synthetic/sandbox credentials.
5. Run searchShopProducts, getShopProduct, and searchShopOrders against test data.
6. Create a Link to a test channel and Match shop variants to channel variants.
7. Exercise webhook creation/deletion and inbound order handling with duplicate, invalid-signature, and wrong-user cases.

There is no current first-shop onboarding mutation or demo seed. Platform and shop records are configured manually after first-user initialization.

Bounded GraphQL operations

The current custom schema includes searchShopProducts, getShopProduct, searchShopOrders, shop webhook queries/mutations, product updates, matching, cart, and order-routing commands. Read the generated schema.graphql from the exact source revision for inputs and result types.

Use those operations only through ownership-checked server paths. Do not expose raw Shop/ShopPlatform credential fields or treat API-key scope strings as enforcement without testing every resolver and related record.

Current limitations

Openship does not provide a customer storefront, payment checkout, product-authority database, or general ecommerce tenant. Current source has no onboarding seed, no complete provider conformance suite, and no durable delivery ledger for every inbound/outbound webhook path. It also permits configurable execution destinations and stores shop credentials in fields that need additional protection.

Before a real source connection, prove token secrecy and rotation, API-key and cross-user denial, OAuth state/callback ownership, signed raw-body webhooks, event replay handling, bounded egress, provider timeout behavior, order idempotency, cancellation after partial routing, and reconciliation against the source shop.

See GraphQL API and Create a custom shop integration.