@misiki/oscar-connector

The Official TypeScript API Connector for connecting svelte-commerce to Oscar E-Commerce Backend.

@misiki/oscar-connector provides a production-ready, fully-typed API client and integration layer that seamlessly bridges svelte-commerce storefronts with Oscar headless e-commerce backends — part of the Litekart connector suite, mirroring the full 43-service surface of @misiki/litekart-connector.

Coverage: 15 of 43 services are wired to the live Django Oscar API. The remaining 28 have no Django Oscar equivalent and return empty placeholder data. Each placeholder says why in a comment at the top of its service file.

🚀 Step-by-Step Integration Guide

Follow these steps to connect svelte-commerce with oscar-connector and your Oscar backend.

1. Install the Connector

Inside your svelte-commerce project directory, run:

bun i @misiki/oscar-connector

(Or using npm / pnpm / yarn):

npm install @misiki/oscar-connector
# or
pnpm add @misiki/oscar-connector

2. Configure kitcommerce.config.ts

In svelte-commerce, open kitcommerce.config.ts and change the export * line to import from @misiki/oscar-connector:

// kitcommerce.config.ts
export * from '@misiki/oscar-connector';

3. Configure Credentials

⚠️ Requires django-oscar-api — a THIRD-PARTY package, not part of Oscar core. A plain Django Oscar install exposes no REST API at all. The store owner must pip install django-oscar-api and mount it, e.g. path("api/", include("oscarapi.urls")). Every endpoint this connector calls comes from that package. If it is mounted somewhere other than /api/, call OscarConnector.setApiBase('/your-prefix') at boot.

Docs: https://django-oscar-api.readthedocs.io · source of truth for the route list: oscarapi/urls.py (the readthedocs "API and URLs" page is currently 404).

Pass apiUrl (the store URL). Authentication is session-based by default: django-oscar-api ships oscarapi.middleware.HeaderSessionMiddleware, and this connector sends/replays the Session-Id: SID:{ANON|AUTH}:{realm}:{id} header. There is no Bearer scheme — Authorization: Bearer … is ignored by every oscarapi endpoint. DRF TokenAuthentication (Authorization: Token <key>) works only if the store wired it up itself; select it with OscarConnector.setAuthMode('token') plus accessToken.

Two store settings gate the customer endpoints, and both default to the restrictive value:

| Django setting | Default | Effect while unset | | --- | --- | --- | | OSCARAPI_EXPOSE_USER_DETAILS | False | GET /api/login/ and GET /api/users/{pk}/ return 204 No Content, so auth.getMe() / profile.getOne() cannot read the account. | | OSCARAPI_ENABLE_REGISTRATION | False | POST /api/register/ returns 401, so auth.signup() fails. | | OSCARAPI_BLOCK_ADMIN_API_ACCESS | True | /api/admin/… is not mounted. This connector never calls it — leave it True. |

import { OscarConnector } from '@misiki/oscar-connector'

// Credentials are set once, statically — the constructor only takes an optional fetch.
OscarConnector.setCredentials({
  apiUrl: 'https://store.example.com',
  accessToken: 'token'
})

const client = new OscarConnector()

const products = await client.product.list({ page: 1, sort: '-createdAt' })

4. Build and Run the Project

Run the development server in svelte-commerce:

bun dev

To build and run the production application:

# Build the project
bun run build

# Preview the built application
bun run preview

Service coverage

| Service | Status | | --- | --- | | client.product | ✅ live | | client.category | ✅ live | | client.collection | ✅ live | | client.order | ✅ live | | client.coupon | ⚠️ placeholder (no Django Oscar equivalent) | | client.address | ✅ live | | client.review | ⚠️ placeholder (no Django Oscar equivalent) | | client.cart | ✅ live | | client.country | ✅ live | | client.state | ⚠️ placeholder (no Django Oscar equivalent) | | client.currency | ⚠️ placeholder (no Django Oscar equivalent) | | client.region | ⚠️ placeholder (no Django Oscar equivalent) | | client.page | ⚠️ placeholder (no Django Oscar equivalent) | | client.blog | ⚠️ placeholder (no Django Oscar equivalent) | | client.settings | ⚠️ placeholder (no Django Oscar equivalent) | | client.store | ✅ live | | client.paymentMethod | ⚠️ placeholder (no Django Oscar equivalent) | | client.search | ⚠️ placeholder (no Django Oscar equivalent) | | client.autocomplete | ⚠️ placeholder (no Django Oscar equivalent) | | client.user | ✅ live | | client.auth | ✅ live | | client.profile | ✅ live | | client.wishlist | ⚠️ placeholder (no Django Oscar equivalent) | | client.vendor | ⚠️ placeholder (no Django Oscar equivalent) | | client.checkout | ✅ live | | client.upload | ⚠️ placeholder (no Django Oscar equivalent) | | client.banner | ⚠️ placeholder (no Django Oscar equivalent) | | client.chat | ⚠️ placeholder (no Django Oscar equivalent) | | client.contact | ⚠️ placeholder (no Django Oscar equivalent) | | client.deal | ⚠️ placeholder (no Django Oscar equivalent) | | client.demoRequest | ⚠️ placeholder (no Django Oscar equivalent) | | client.enquiry | ⚠️ placeholder (no Django Oscar equivalent) | | client.faq | ⚠️ placeholder (no Django Oscar equivalent) | | client.feedback | ⚠️ placeholder (no Django Oscar equivalent) | | client.gallery | ⚠️ placeholder (no Django Oscar equivalent) | | client.home | ✅ live | | client.init | ✅ live | | client.meilisearch | ⚠️ placeholder (no Django Oscar equivalent) | | client.menu | ✅ live | | client.plugins | ⚠️ placeholder (no Django Oscar equivalent) | | client.popularSearch | ⚠️ placeholder (no Django Oscar equivalent) | | client.popularity | ⚠️ placeholder (no Django Oscar equivalent) | | client.reels | ⚠️ placeholder (no Django Oscar equivalent) |

Development

bun install && bun run typecheck && bun run build

License

MIT © misiki-in