Proxima - Swell Storefront App

https://github.com/swellstores/proxima-app
Admin
Proxima is an official Swell storefront app built with Astro and React, offering a modern,...
Tokens:49,257
Snippets:376
Trust Score:7.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start development mode

Source: https://github.com/swellstores/proxima-app/blob/master/README.md

Starts the local development server and opens the browser to preview the app.

```bash
swell app dev
```

--------------------------------

### initTheme usage example

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Example of initializing the swell client and theme, then rendering a page.

```ts
import { initSwell, initTheme } from '@/swell';

const swell = initSwell(Astro);
const theme = initTheme(swell);
await theme.initGlobals('index');
const html = await theme.renderPage();
```

--------------------------------

### Install dependencies

Source: https://github.com/swellstores/proxima-app/blob/master/README.md

Installs project dependencies using npm.

```bash
npm install
```

--------------------------------

### parseResources output example

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/utils.md

Shows the expected JSON output shape for a GET /products/:slug.json request, where the product value is transformed into an object with a _resource marker and the resolved value.

```typescript
// GET /products/:slug.json →
// { "product": { "_resource": "ProductResource", "value": { ... } } }
```

--------------------------------

### Install Swell CLI globally

Source: https://github.com/swellstores/proxima-app/blob/master/README.md

Installs the Swell CLI globally using npm, required for development.

```bash
npm install -g @swell/cli
```

--------------------------------

### initSwellTheme usage example

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Example of using initSwellTheme in a request handler to fetch the cart.

```ts
async function getHandler(Astro: AstroGlobal) {
  const { swell, theme } = await initSwellTheme(Astro);
  const cart = await theme.fetchCart();
  return cart;
}
```

--------------------------------

### handleMiddlewareRequest usage example

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/server.md

Example of using handleMiddlewareRequest to create a logout handler for GET requests to '/account/logout'. The handler calls the storefront account logout and redirects to '/' with a 303 status.

```ts
const doLogout = handleMiddlewareRequest(
  'GET',
  '/account/logout',
  async ({ swell, context }: SwellServerContext) => {
    await swell.storefront.account.logout();
    return context.redirect('/', 303);
  },
);
```

--------------------------------

### Example usage of createHtmlCache

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/utils.md

Shows how to import and use createHtmlCache to get a cache instance and check for a cached response. If the cache exists and a cached response is found, it returns that response.

```typescript
import { createHtmlCache } from '@/utils/html-cache';

const cache = createHtmlCache(context);
if (cache) {
  const cached = await cache.get(request);
  if (cached?.found && cached.response) { return cached.response; }
}
```

--------------------------------

### Example: persist session id with cookie helpers

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Middleware example showing how to set, get, and delete a session cookie using the namespaced helpers. The setCookie call is conditional on a session variable.

```typescript
// Middleware: persist a session id forwarded by the storefront
if (session) {
  setCookie(context, 'swell-session', session);
}
const session = getCookie(context, 'swell-session');
deleteCookie(context, 'swell-session');
```

--------------------------------

### GET /account/signup

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the signup HTML page. Public access.

```APIDOC
## GET /account/signup

### Description
Returns the signup HTML page. Public access.

### Method
GET

### Endpoint
/account/signup

### Authentication
Public

### Response
#### Success Response (200)
- **body** (HTML) - Signup HTML page (page id `account/signup`).

```

--------------------------------

### GET /cart.js

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns cart JSON when the Accept header starts with 'application/json' or '*/*'.

```APIDOC
## GET /cart.js

### Description
Returns cart JSON when the Accept header starts with 'application/json' or '*/*'.

### Method
GET

### Endpoint
/cart.js

### Parameters
#### Headers
- **Accept** (string) - Required - Must start with 'application/json' or '*/*' to receive JSON response.

### Response
#### Success Response (200)
- **body** (JSON) - Cart data.

#### Response Example
```json
{
  "cart": {}
}
```
```

--------------------------------

### Example usage of initSwell in an API route

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Shows how to initialize the Swell client and fetch storefront settings in an Astro API route.

```typescript
import { initSwell } from '@/swell';

export const GET: APIRoute = async (context) => {
  const swell = initSwell(context);
  const storefront = await swell.getStorefrontSettings();
  return new Response(JSON.stringify(storefront));
};
```

--------------------------------

### ThemePage usage example

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/theme-rendering.md

Shows how to use the ThemePage component in a page, passing the id, required, title, description, and getData props.

```astro
<ThemePage
  id="products/product"
  required="product.id"
  title="{{ product.meta_title | default: product.name }}"
  description="{{ product.meta_description | default: product.description }}"
  getData={(swell: Swell) => getData(swell, Astro.params.slug)}
/>
```

--------------------------------

### Logger usage example

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/utils.md

Shows how to configure the logger and log an info message with a trace ID.

```typescript
import { configureProximaLogger, logger, createTraceId } from '@/utils/logger';

configureProximaLogger({ level: 'debug', structured: true });
logger.info('checkout started', { traceId: createTraceId() });
```

--------------------------------

### GET /

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the HTML homepage for the storefront. This is the root endpoint that serves the index page.

```APIDOC
## GET /

### Description
Returns the HTML homepage for the storefront. This is the root endpoint that serves the index page.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- HTML homepage content

#### Response Example
```html
<!DOCTYPE html>
<html>...</html>
```
```

--------------------------------

### GET /robots.txt - Robots.txt handler stub

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Defines the GET handler for /robots.txt. The implementation is omitted (shown as ...). The surrounding documentation describes initialization, rendering, and fallback behavior.

```TypeScript
export const GET: APIRoute = async (context) => { ... };
```

--------------------------------

### GET /sitemap:index.xml

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Alias for sitemap generation with an index parameter, re-exported from sitemap.xml.ts. Behaves identically to GET /sitemap.xml.

```APIDOC
## GET /sitemap:index.xml

### Description
Alias for sitemap generation with an index parameter, re-exported from sitemap.xml.ts. Behaves identically to GET /sitemap.xml.

### Method
GET

### Endpoint
/sitemap:index.xml

### Parameters
#### Path Parameters
- **index** (number) - Required - Sitemap index (default 0). Invalid or negative values return 404.

### Response
#### Success Response (200)
- **Content-Type** (string) - `application/xml`
- **Last-Modified** (string) - Header with last modified date.
- **X-Pages-Count** (number) - Only for file 0 of a multi-file sitemap; number of chunk files.

#### Response Example
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
  </url>
</urlset>

### Error Handling
- **404** - If index is invalid/negative or if paged sitemap is inconsistent with cached main sitemap's `X-Pages-Count` header.
```

--------------------------------

### GET /products/:slug.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Returns product data as resource-parsed JSON. Uses getData to build a ProductResource and serializes it with parseResources.

```APIDOC
## GET /products/:slug.json

### Description
Returns product data as resource-parsed JSON. Uses getData to build a ProductResource and serializes it with parseResources.

### Method
GET

### Endpoint
/products/:slug.json

### Parameters
#### Path Parameters
- **slug** (string) - Required - The product slug.

#### Query Parameters
- **options** (object) - Optional - Product options for pricing.
- **purchase_option** (string) - Optional - Purchase option for pricing.
- **quantity** (number) - Optional - Quantity for pricing, default 1.

### Response
#### Success Response (200)
- **product** (object) - The product resource data.

#### Response Example
{
  "product": {}
}
```

--------------------------------

### GET /categories

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves the category list as an HTML page.

```APIDOC
## GET /categories

### Description
Retrieves the category list as an HTML page.

### Method
GET

### Endpoint
/categories

### Response
#### Success Response (200)
- **body** (HTML) - Category list HTML (page id `categories/index`)

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /products/:slug.js

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Returns product data as Shopify-adapted, resolved JSON for theme scripts. Adapts data if theme.shopifyCompatibility is enabled and resolves the product resource.

```APIDOC
## GET /products/:slug.js

### Description
Returns product data as Shopify-adapted, resolved JSON for theme scripts. Adapts data if theme.shopifyCompatibility is enabled and resolves the product resource.

### Method
GET

### Endpoint
/products/:slug.js

### Parameters
#### Path Parameters
- **slug** (string) - Required - The product slug.

#### Query Parameters
- **options** (object) - Optional - Product options for pricing.
- **purchase_option** (string) - Optional - Purchase option for pricing.
- **quantity** (number) - Optional - Quantity for pricing, default 1.

### Response
#### Success Response (200)
- **product** (object) - The resolved product data.

#### Response Example
{
  "product": {}
}
```

--------------------------------

### GET /cart.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Retrieves the current cart.

```APIDOC
## GET /cart.json

### Description
Retrieves the current cart.

### Method
GET

### Endpoint
/cart.json

### Response
#### Success Response (200)
- **cart** (CartResource) - The cart resource.

#### Response Example
{
  "cart": {}
}
```

--------------------------------

### GET /products.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Returns category and optionally product data based on query parameters. Uses getData to build CategoryResource and ProductResource.

```APIDOC
## GET /products.json

### Description
Returns category and optionally product data based on query parameters. Uses getData to build CategoryResource and ProductResource.

### Method
GET

### Endpoint
/products.json

### Parameters
#### Query Parameters
- **product_id** (string) - Optional - The product ID to include product data.
- **category** (string) - Optional - The category ID, defaults to 'all'.

### Response
#### Success Response (200)
- **category** (object) - The category resource data.
- **product** (object|null) - The product resource data if product_id provided, otherwise null.

#### Response Example
{
  "category": {},
  "product": null
}
```

--------------------------------

### GET /blogs/:slug

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a blog category as an HTML page.

```APIDOC
## GET /blogs/:slug

### Description
Retrieves a blog category as an HTML page.

### Method
GET

### Endpoint
/blogs/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The blog category slug.

### Response
#### Success Response (200)
- **body** (HTML) - Blog category HTML (page id `blogs/category`).

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /products

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the product list HTML page. Supports optional query parameters for filtering by product ID or category.

```APIDOC
## GET /products

### Description
Returns the product list HTML page. Supports optional query parameters for filtering by product ID or category.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **product_id** (string) - Optional - Filter products by product ID.
- **category** (string) - Optional - Filter products by category.

### Response
#### Success Response (200)
- HTML product list content

#### Response Example
```html
<!DOCTYPE html>
<html>...</html>
```
```

--------------------------------

### GET /assets/:asset_name

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Renders an asset dynamically. Returns a 404 if the asset config is not found and a 500 on render errors.

```APIDOC
## GET /assets/:asset_name

### Description
Renders an asset dynamically. Returns a 404 if the asset config is not found and a 500 on render errors.

### Method
GET

### Endpoint
/assets/:asset_name

### Parameters
#### Path Parameters
- **asset_name** (string) - Required - The name of the asset.

### Response
#### Success Response (200)
- Rendered asset with `Cache-Control: no-cache` and `X-Cache-Status: DYNAMIC`.

#### Error Response (404)
- `Asset config not found: {name}`

#### Error Response (500)
- On render error.

```

--------------------------------

### GET /categories/:slug/products/:product

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a product within a category, combining product and category data.

```APIDOC
## GET /categories/:slug/products/:product

### Description
Retrieves a product within a category, combining product and category data.

### Method
GET

### Endpoint
/categories/:slug/products/:product

### Parameters
#### Path Parameters
- **slug** (string) - Required - The category slug.
- **product** (string) - Required - The product slug.

### Response
#### Success Response (200)
- **body** (HTML) - Product within a category HTML.

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /account

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the account dashboard HTML page. Requires login.

```APIDOC
## GET /account

### Description
Returns the account dashboard HTML page. Requires login.

### Method
GET

### Endpoint
/account

### Authentication
Login guard required.

### Response
#### Success Response (200)
- **body** (HTML) - Account HTML page (page id `account/index`).

```

--------------------------------

### GET /resources/:slug - Dynamic resource access

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Handles GET requests to /resources/:slug. Parses query params for path, slug, and JSON-encoded query. Instantiates the resource class from the resources map and resolves it, optionally calling a method path. Returns the resolved resource or null.

```TypeScript
export const GET = handleServerRequest(async ({ swell, params, context }) => {
  const { slug: resource_slug } = context.params as { slug: keyof typeof resources };
  const { path, slug = '' } = params;
  const query = JSON.parse(params.query);

  const Resource = resources[resource_slug];

  let resource;
  if (path) {
    resource = await new Resource(swell, slug, query)[path.replace('/', '.')];
    resource = await resource.resolve(false);
  } else {
    resource = await new Resource(swell, slug, query).resolve(false);
  }

  return resource ?? null;
});
```

--------------------------------

### GET /products/:slug

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the product HTML page for a given product slug. If the product is not found, a 404 page is returned. Query parameters drive pricing.

```APIDOC
## GET /products/:slug

### Description
Returns the product HTML page for a given product slug. If the product is not found, a 404 page is returned. Query parameters drive pricing.

### Method
GET

### Endpoint
/products/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The product slug.

#### Query Parameters
- **options** (object) - Optional - Product options for pricing.
- **purchase_option** (string) - Optional - Purchase option for pricing.
- **quantity** (number) - Optional - Quantity for pricing.

### Response
#### Success Response (200)
- HTML product page content

#### Response Example
```html
<!DOCTYPE html>
<html>...</html>
```
```

--------------------------------

### GET /blogs/:category/:slug

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a blog post as an HTML page.

```APIDOC
## GET /blogs/:category/:slug

### Description
Retrieves a blog post as an HTML page.

### Method
GET

### Endpoint
/blogs/:category/:slug

### Parameters
#### Path Parameters
- **category** (string) - Required - The blog category slug.
- **slug** (string) - Required - The blog post slug.

### Response
#### Success Response (200)
- **body** (HTML) - Blog post HTML (page id `blogs/blog`).

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /search/suggest

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns predictive search HTML. Accepts a query parameter 'q' for the search term.

```APIDOC
## GET /search/suggest

### Description
Returns predictive search HTML. Accepts a query parameter 'q' for the search term.

### Method
GET

### Endpoint
/search/suggest

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query string.

### Response
#### Success Response (200)
- **body** (HTML) - Predictive search HTML.

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /products/:slug/:variant.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Opens a product with a specific variant selected. This endpoint is associated with the theme page 'products/product'.

```APIDOC
## GET /products/:slug/:variant.json

### Description
Opens a product with a specific variant selected.

### Method
GET

### Endpoint
/products/:slug/:variant.json

### Parameters
#### Path Parameters
- **slug** (string) - Required - The product slug.
- **variant** (string) - Required - The variant identifier.

### Response
#### Success Response (200)
- **product** (object) - The product resource.

#### Response Example
{
  "product": {}
}
```

--------------------------------

### GET /blogs/:slug.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a blog category in JSON format.

```APIDOC
## GET /blogs/:slug.json

### Description
Retrieves a blog category in JSON format.

### Method
GET

### Endpoint
/blogs/:slug.json

### Parameters
#### Path Parameters
- **slug** (string) - Required - The blog category slug.

### Response
#### Success Response (200)
- **category** (object) - The blog category data.

#### Response Example
```json
{
  "category": {}
}
```
```

--------------------------------

### GET /sitemap.xml

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Generates a sitemap XML file with site links, supporting pagination and caching. Returns XML content with appropriate headers.

```APIDOC
## GET /sitemap.xml

### Description
Generates a sitemap XML file with site links, supporting pagination and caching. Returns XML content with appropriate headers.

### Method
GET

### Endpoint
/sitemap.xml

### Parameters
#### Query Parameters
- **index** (number) - Optional - Sitemap index (default 0). Invalid or negative values return 404.

### Response
#### Success Response (200)
- **Content-Type** (string) - `application/xml`
- **Last-Modified** (string) - Header with last modified date.
- **X-Pages-Count** (number) - Only for file 0 of a multi-file sitemap; number of chunk files.

#### Response Example
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
  </url>
</urlset>

### Error Handling
- **404** - If index is invalid/negative or if paged sitemap is inconsistent with cached main sitemap's `X-Pages-Count` header.
```

--------------------------------

### GET /pages/:slug

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a content page as an HTML page.

```APIDOC
## GET /pages/:slug

### Description
Retrieves a content page as an HTML page.

### Method
GET

### Endpoint
/pages/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The page slug.

### Response
#### Success Response (200)
- **body** (HTML) - Content page HTML (page id `pages/page`).

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /variants/:id

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns a product variant resource with its parent product.

```APIDOC
## GET /variants/:id

### Description
Returns a product variant resource with its parent product.

### Method
GET

### Endpoint
/variants/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The variant ID.

### Response
#### Success Response (200)
- **product_variant** (object) - Variant resource with parent product.

#### Response Example
```json
{
  "product_variant": {}
}
```
```

--------------------------------

### GET /search

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the search page HTML. Accepts a query parameter 'q' for the search term.

```APIDOC
## GET /search

### Description
Returns the search page HTML. Accepts a query parameter 'q' for the search term.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query string.

### Response
#### Success Response (200)
- **body** (HTML) - Search page HTML.

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### GET /account/orders/:id

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the order HTML page. Requires login.

```APIDOC
## GET /account/orders/:id

### Description
Returns the order HTML page. Requires login.

### Method
GET

### Endpoint
/account/orders/:id

### Path Parameters
- **id** (string) - Required - The order ID.

### Authentication
Login guard required.

### Response
#### Success Response (200)
- **body** (HTML) - Order HTML page (page id `account/order`).

```

--------------------------------

### GET /resources/:slug

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Provides dynamic access to any resource class in `@/resources` (e.g., ProductResource, CartResource) using query parameters for path, slug, and query.

```APIDOC
## GET /resources/:slug

### Description
Dynamic access to any resource class in `@/resources` (e.g. `ProductResource`, `CartResource`, …). Used by theme scripts to fetch arbitrary resources.

### Method
GET

### Endpoint
/resources/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The resource slug (e.g., 'products', 'carts').

#### Query Parameters
- **path** (string) - Optional - Method path with `/` replaced by `.` (e.g., 'variants' or 'products.variants').
- **slug** (string) - Optional - Additional slug for the resource.
- **query** (string) - Required - JSON-encoded query object.

### Response
#### Success Response (200)
- **resource** (object|null) - The resolved resource or null.

#### Response Example
{
  "resource": {}
}
```

--------------------------------

### GET /cart

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the cart HTML, or cart JSON when the request Accept header is 'application/json'.

```APIDOC
## GET /cart

### Description
Returns the cart HTML, or cart JSON when the request Accept header is 'application/json'.

### Method
GET

### Endpoint
/cart

### Parameters
#### Headers
- **Accept** (string) - Optional - Set to 'application/json' to receive JSON response.

### Response
#### Success Response (200)
- **body** (HTML or JSON) - Cart HTML or cart JSON.

#### Response Example
```html
<!-- HTML content -->
```
```json
{
  "cart": {}
}
```
```

--------------------------------

### GET /robots.txt

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Generates the robots.txt file, either by rendering a theme page or falling back to default groups from theme globals.

```APIDOC
## GET /robots.txt

### Description
Generates the robots.txt file. It initializes the theme, attempts to render a page, and falls back to default groups if the page is not found.

### Method
GET

### Endpoint
/robots.txt

### Response
#### Success Response (200)
- **body** (string) - Plain text content of robots.txt.

#### Response Example
User-agent: *
Allow: /
```

--------------------------------

### blogs/[category]/index.astro getData

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Returns a blog category resource for a blog category slug. Theme page id="blogs/category", required category.id; GET /blogs/:category.json.

```typescript
export async function getData(swell: Swell, category?: string) {
  return { category: new BlogCategoryResource(swell, category as string) };
}
```

--------------------------------

### GET /assets/v/:version/:asset_name

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a cached or rendered asset for a given version. Returns a 400 error if the version exceeds 64 characters.

```APIDOC
## GET /assets/v/:version/:asset_name

### Description
Retrieves a cached or rendered asset for a given version. Returns a 400 error if the version exceeds 64 characters.

### Method
GET

### Endpoint
/assets/v/:version/:asset_name

### Parameters
#### Path Parameters
- **version** (string) - Required - The version identifier for the asset.
- **asset_name** (string) - Required - The name of the asset.

### Response
#### Success Response (200)
- Cached or rendered asset with long-lived `Cache-Control` (immutable).
- `X-Cache-Status: HIT|MISS`

#### Error Response (400)
- When version > 64 characters.

```

--------------------------------

### GET /products/:slug/:variant

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the variant-selected product HTML page. Resolves the variant and sets the variant query parameter. The .json version returns product data.

```APIDOC
## GET /products/:slug/:variant

### Description
Returns the variant-selected product HTML page. Resolves the variant and sets the variant query parameter. The .json version returns product data.

### Method
GET

### Endpoint
/products/:slug/:variant

### Parameters
#### Path Parameters
- **slug** (string) - Required - The product slug.
- **variant** (string) - Required - The variant identifier.

### Response
#### Success Response (200)
- HTML product page with variant selected

#### Response Example
```html
<!DOCTYPE html>
<html>...</html>
```
```

--------------------------------

### GET /account/recover{/:password_reset_key}?

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Validates the password reset key and sets the `password_reset_key` global or an `invalid_reset_key` form error. Public access.

```APIDOC
## GET /account/recover{/:password_reset_key}?

### Description
Validates the password reset key and sets the `password_reset_key` global or an `invalid_reset_key` form error. Public access.

### Method
GET

### Endpoint
/account/recover{/:password_reset_key}?

### Path Parameters
- **password_reset_key** (string) - Optional - The password reset key to validate.

### Authentication
Public

### Response
#### Success Response (200)
- **password_reset_key** (string) - Set as a global if the key is valid.

#### Error Response (303)
- **Location** (string) - Redirect to `/account/login` if no key is provided.
- **invalid_reset_key** (form error) - Set if the key is invalid.

```

--------------------------------

### initSwell

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Initializes the Swell storefront client for the current request. It reads the request context, loads configuration files, and returns a Swell instance bound to the request.

```APIDOC
## initSwell

### Description
Initializes the `Swell` storefront client for the current request. It wires the SDK into the Astro request context, configures logger and cookie adapters, and loads app configuration from `swell.json` and `shopify_compatibility.json`.

### Method
Function

### Signature
```ts
export function initSwell(
  context: AstroGlobal | APIContext,
  options?: Record<string, unknown>,
): Swell
```

### Parameters
- **context** (`AstroGlobal | APIContext`) - Required - Astro request context. Reads `context.locals.runtime.env` (Cloudflare bindings) and `context.locals.runtime.ctx` (worker execution context).
- **options** (`Record<string, unknown>`) - Optional - Extra overrides spread last onto the `Swell` constructor, so they win over defaults.

### Constructor Options
| Option | Value |
|--------|-------|
| `url` | `context.url` |
| `shopifyCompatibilityConfig` | contents of `shopify_compatibility.json` (cast to `SwellAppShopifyCompatibilityConfig`) |
| `config` | contents of `swell.json` (cast to `SwellAppConfig`) |
| `serverHeaders` | `context.request.headers` |
| `workerEnv` | `context.locals.runtime?.env` (as `CFThemeEnv`) |
| `workerCtx` | `context.locals.runtime?.ctx` (as `CFWorkerContext`) |
| `logger` | only added if any of `LOG_LEVEL` / `STRUCTURED_LOGS` env vars are set — `{ level: env.LOG_LEVEL, structured: env.STRUCTURED_LOGS === 'true' }` |
| `getCookie` / `setCookie` / `deleteCookie` | adapters over the `swell-data` cookie (see cookie helpers below); set/delete are skipped when `canUpdateCookies` is false |

### Returns
`Swell` — the initialized storefront SDK client bound to the request context.

### Example
```ts
import { initSwell } from '@/swell';

export const GET: APIRoute = async (context) => {
  const swell = initSwell(context);
  const storefront = await swell.getStorefrontSettings();
  return new Response(JSON.stringify(storefront));
};
```

### Source
`frontend/src/swell.ts` lines 27–77.
```

--------------------------------

### GET /categories/:slug/products/:product.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Combines category and product data for a product within a category. This endpoint is associated with the theme page 'products/product'.

```APIDOC
## GET /categories/:slug/products/:product.json

### Description
Combines category and product data for a product within a category.

### Method
GET

### Endpoint
/categories/:slug/products/:product.json

### Parameters
#### Path Parameters
- **slug** (string) - Required - The category slug.
- **product** (string) - Required - The product slug.

### Response
#### Success Response (200)
- **productData** (object) - The product data.
- **categoryData** (object) - The category data.

#### Response Example
{
  "productData": {},
  "categoryData": {}
}
```

--------------------------------

### blogs/[category]/[slug].astro getData

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Returns a blog resource for a specific blog post within a category. Theme page id="blogs/blog", required blog.id; GET /blogs/:category/:slug.json.

```typescript
export async function getData(swell: Swell, slug?: string, category?: string) {
  return { blog: new BlogResource(swell, slug as string, category as string) };
}
```

--------------------------------

### initializeLoggerFromEnv

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/utils.md

Initializes the logger from environment variables. Reads LOG_LEVEL and STRUCTURED_LOGS, then calls configureProximaLogger.

```APIDOC
## initializeLoggerFromEnv

### Description
Reads `LOG_LEVEL` (cast to `LogLevel`) and `STRUCTURED_LOGS === 'true'`, then calls `configureProximaLogger`. Invoked by the `initLogger` middleware and by `initSwell` (logger config passed to the `Swell` constructor).

### Method
Function

### Signature
```ts
export function initializeLoggerFromEnv(env: {
  LOG_LEVEL?: string;
  STRUCTURED_LOGS?: string;
}): void
```

### Parameters
#### env Object
- **LOG_LEVEL** (`string`) - Optional - The log level to set.
- **STRUCTURED_LOGS** (`string`) - Optional - If `'true'`, enables structured logging.

### Returns
`void`
```

--------------------------------

### Push app to development store

Source: https://github.com/swellstores/proxima-app/blob/master/README.md

Pushes the app configuration to your development store.

```bash
swell app push
```

--------------------------------

### GET /variants/:id - Resolve variant with parent product

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Handles GET requests to /variants/:id. Extracts the id from context params, fetches the variant record to get its parent_id, then constructs ProductResource and VariantResource to return a product_variant object.

```TypeScript
export const GET = handleServerRequest(async ({ context, swell }) => {
  const { id } = context.params;

  const variantRecord = await swell.get('/products:variants/{id}', {
    id,
    fields: 'parent_id',
  });

  const product = new ProductResource(swell, variantRecord?.parent_id);
  const product_variant = new VariantResource(swell, product, id as string);

  return { product_variant };
});
```

--------------------------------

### initTheme(swell)

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Builds a SwellTheme instance pre-configured with Proxima forms, resources from swell.json, the dynamic asset URL, and a custom Shopify compatibility class.

```APIDOC
## initTheme(swell)

### Description
Builds the `SwellTheme` instance with Proxima's forms (`@/forms`), resources declared in `swell.json` (`swellConfig.storefront.theme.resources`), the dynamic asset URL, and the custom Shopify compatibility class.

### Method
Function

### Signature
```ts
export function initTheme(swell: Swell): SwellTheme
```

### Parameters
- `swell` (Swell) - Required - Initialized storefront client

### Returns
`SwellTheme` — theme renderer pre-configured with Proxima forms and resources.

### Example
```ts
import { initSwell, initTheme } from '@/swell';

const swell = initSwell(Astro);
const theme = initTheme(swell);
await theme.initGlobals('index');
const html = await theme.renderPage();
```

### Source
`frontend/src/swell.ts` lines 137–154.
```

--------------------------------

### Cart middleware route mappings

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/middleware.md

Defines cart middleware handlers for GET /cart and /cart.js, GET /cart/change, and POST /cart. Handlers are referenced from forms.md.

```typescript
const getCart = handleMiddlewareRequest('GET', ['/cart', '/cart.js'], cartGet);
const updateCart = handleMiddlewareRequest('GET', '/cart/change', cartUpdate);
const submitCheckout = handleMiddlewareRequest('POST', '/cart', cartCheckout);

export default [getCart, updateCart, submitCheckout];
```

--------------------------------

### GET /checkout

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Redirects to cart.checkout_url or /cart with a 303 status.

```APIDOC
## GET /checkout

### Description
Redirects to cart.checkout_url or /cart with a 303 status.

### Method
GET

### Endpoint
/checkout

### Response
#### Success Response (303)
- **Location** (string) - Redirect location to cart.checkout_url or /cart.

#### Response Example
```
HTTP/1.1 303 See Other
Location: /cart
```
```

--------------------------------

### initSwellTheme(Astro)

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/swell.md

Request-scoped bootstrap that returns the singleton Swell client and theme for the current request, reusing them if already present in Astro.locals.

```APIDOC
## initSwellTheme(Astro)

### Description
Request-scoped bootstrap used by every page. If `Astro.locals.swell` exists it is reused, otherwise `initSwell` is called; if reused, `swell.sentResponse = true` is set to prevent cookie mutation. The theme is reused from `Astro.locals.theme` or created via `initTheme`.

### Method
Function

### Signature
```ts
export async function initSwellTheme(
  Astro: AstroGlobal | APIContext,
): Promise<{ swell: Swell; theme: SwellTheme }>
```

### Parameters
- `Astro` (AstroGlobal | APIContext) - Required - The Astro global or API context for the current request.

### Returns
`Promise<{ swell: Swell; theme: SwellTheme }>` — resolves the singleton pair for the current request.

### Example
```ts
async function getHandler(Astro: AstroGlobal) {
  const { swell, theme } = await initSwellTheme(Astro);
  const cart = await theme.fetchCart();
  return cart;
}
```

### Source
`frontend/src/swell.ts` lines 156–169.
```

--------------------------------

### GET /account/subscriptions/:id.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Retrieves an account subscription by its ID.

```APIDOC
## GET /account/subscriptions/:id.json

### Description
Retrieves an account subscription by its ID.

### Method
GET

### Endpoint
/account/subscriptions/:id.json

### Parameters
#### Path Parameters
- **id** (string) - Required - The subscription ID.

### Response
#### Success Response (200)
- **subscription** (AccountSubscriptionResource) - The subscription resource.

#### Response Example
{
  "subscription": {}
}
```

--------------------------------

### GET /account/orders/:id.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Retrieves an account order by its ID.

```APIDOC
## GET /account/orders/:id.json

### Description
Retrieves an account order by its ID.

### Method
GET

### Endpoint
/account/orders/:id.json

### Parameters
#### Path Parameters
- **id** (string) - Required - The order ID.

### Response
#### Success Response (200)
- **order** (AccountOrderResource) - The order resource.

#### Response Example
{
  "order": {}
}
```

--------------------------------

### POST /account, POST /account/signup

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Creates a new account with first name, last name, email, and password. On success, redirects to the account page; on failure, redirects to the signup page.

```APIDOC
## POST /account, POST /account/signup

### Description
Creates a new account with first name, last name, email, and password. On success, redirects to the account page; on failure, redirects to the signup page.

### Method
POST

### Endpoint
/account or /account/signup

### Authentication
Public

### Request Body
- **account** (object) - Required
  - **first_name** (string) - Required - The user's first name.
  - **last_name** (string) - Required - The user's last name.
  - **email** (string) - Required - The user's email.
  - **password** (string) - Required - The user's password.

### Request Example
```json
{
  "account": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "password": "secret"
  }
}
```

### Response
#### Success Response (303)
- **Location** (string) - Redirect to `/account`.

#### Error Response (303)
- **Location** (string) - Redirect to `/account/signup`.

```

--------------------------------

### GET /pages/:slug.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Retrieves a page resource by its slug.

```APIDOC
## GET /pages/:slug.json

### Description
Retrieves a page resource by its slug.

### Method
GET

### Endpoint
/pages/:slug.json

### Parameters
#### Path Parameters
- **slug** (string) - Required - The page slug.

### Response
#### Success Response (200)
- **page** (PageResource) - The page resource.

#### Response Example
{
  "page": {}
}
```

--------------------------------

### Login to Swell

Source: https://github.com/swellstores/proxima-app/blob/master/README.md

Authenticates with Swell CLI.

```bash
swell login
```

--------------------------------

### Import accountLogin from forms/account

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/forms.md

Shows how to import the accountLogin handler. Registered for POST /account/login.

```TypeScript
import { accountLogin } from '@/forms/account';
```

--------------------------------

### GET /account/addresses

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the addresses HTML page. Requires login.

```APIDOC
## GET /account/addresses

### Description
Returns the addresses HTML page. Requires login.

### Method
GET

### Endpoint
/account/addresses

### Authentication
Login guard required.

### Response
#### Success Response (200)
- **body** (HTML) - Addresses HTML page (page id `account/addresses`).

```

--------------------------------

### GET /account/login

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Returns the login HTML page. Public access.

```APIDOC
## GET /account/login

### Description
Returns the login HTML page. Public access.

### Method
GET

### Endpoint
/account/login

### Authentication
Public

### Response
#### Success Response (200)
- **body** (HTML) - Login HTML page (page id `account/login`).

```

--------------------------------

### GET /content/:collection.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a custom collection in JSON format.

```APIDOC
## GET /content/:collection.json

### Description
Retrieves a custom collection in JSON format.

### Method
GET

### Endpoint
/content/:collection.json

### Parameters
#### Path Parameters
- **collection** (string) - Required - The collection name.

### Response
#### Success Response (200)
- **model** (object) - The model data.
- **entries** (array) - The entries data.

#### Response Example
```json
{
  "model": {},
  "entries": []
}
```
```

--------------------------------

### GET /content/:collection

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/endpoints.md

Retrieves a custom collection as an HTML page.

```APIDOC
## GET /content/:collection

### Description
Retrieves a custom collection as an HTML page.

### Method
GET

### Endpoint
/content/:collection

### Parameters
#### Path Parameters
- **collection** (string) - Required - The collection name.

### Response
#### Success Response (200)
- **body** (HTML) - Custom collection HTML (page id `content/index`).

#### Response Example
```html
<!-- HTML content -->
```
```

--------------------------------

### Project structure tree

Source: https://github.com/swellstores/proxima-app/blob/master/README.md

Shows the directory layout of the Proxima app, including frontend, assets, settings, and configuration files.

```text
proxima/
├── frontend/                    # Astro frontend application
│   ├── src/
│   │   ├── components/         # Reusable UI components
│   │   ├── layouts/            # Page layout templates
│   │   ├── pages/              # Route definitions and page components
│   │   │   ├── account/        # Customer account pages
│   │   │   ├── blogs/          # Blog and content pages
│   │   │   ├── cart/           # Shopping cart functionality
│   │   │   ├── categories/     # Product category pages
│   │   │   ├── products/       # Product listing and detail pages
│   │   │   └── search/         # Search functionality
│   │   ├── resources/          # Data fetching and API integration
│   │   ├── forms/              # Form handling components
│   │   └── utils/              # Utility functions and helpers
│   └── public/                 # App's own static assets
├── assets/                     # App assets and marketing materials
├── settings/                   # App configuration settings
└── swell.json                  # Swell app configuration
```

--------------------------------

### handleMiddlewareRequest

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/server.md

Creates an Astro MiddlewareHandler that only runs when the request method matches the specified method and the URL matches the given pattern. It merges matched path parameters into the server context and handles responses appropriately.

```APIDOC
## handleMiddlewareRequest

### Description
Creates an Astro `MiddlewareHandler` that only runs when `method` matches the request method and the URL matches `urlParam`. Non-matching requests short-circuit to `next()`. Matched path parameters are merged into `serverContext.params`. If the handler returns a `Response`, theme request data is preserved and the response goes through `handleResponse`. Returning `undefined` falls through to `next()`. Other return values are serialized via `sendServerResponse`; thrown errors via `sendServerError`.

### Method
N/A (Function)

### Endpoint
N/A (Function)

### Parameters
#### Function Parameters
- **method** (string) - Required - HTTP method to gate on (e.g. `'GET'`, `'POST'`).
- **urlParam** (string | string[] | ((pathname) => boolean)) - Required - Path pattern(s). Strings are compiled with `path-to-regexp` (`match`), except patterns containing `!` which use `minimatch` for negation. A function receives `pathname` and returns a boolean.
- **handler** ((context, next) => unknown) - Required - The handler. Receives `SwellServerContext` and `SwellServerNext`.

### Request Example
```ts
const doLogout = handleMiddlewareRequest(
  'GET',
  '/account/logout',
  async ({ swell, context }: SwellServerContext) => {
    await swell.storefront.account.logout();
    return context.redirect('/', 303);
  },
);
```

### Response
#### Success Response
- Returns a `MiddlewareHandler` that conditionally executes the provided handler.

#### Response Example
N/A

### Source
`frontend/src/utils/server.ts` lines 106–151.
```

--------------------------------

### GET /search/suggest.json

Source: https://github.com/swellstores/proxima-app/blob/master/_autodocs/api-reference/pages.md

Returns predictive search suggestions based on a query.

```APIDOC
## GET /search/suggest.json

### Description
Returns predictive search suggestions based on a query.

### Method
GET

### Endpoint
/search/suggest.json

### Parameters
#### Query Parameters
- **q** (string) - Optional - The search query.

### Response
#### Success Response (200)
- **predictive_search** (PredictiveSearchResource) - The predictive search results.

#### Response Example
{
  "predictive_search": {}
}
```
Tokens:
Raw