Custom apps' records

A custom app installed on the store (app-registry card) may own record types the storefront shows: a store locator's locations, a lookbook's looks. They are metaobjects the app owns, typed <app key>.<record type>, and the storefront reads them exactly as it reads any metaobject, with the publishable key. Public types only, active records only: an app's private type (its mapping table, its sync log) is 404 here.

The whole app story for an agent building one is in docs/apps/ (the manifest, the app's own API, the CLI). This page is the storefront's half.

GET /api/store/metaobjects/:app.:type — an app's records

• Purpose: the active records of one of an app's public record types, newest-updated first, raw field values.
• Auth: anon (x-client-id) or the publishable key.
• Request: query {limit?, offset?} (limit 1 to 100, default 20).
• Response: {metaobjects: [Metaobject…], count, offset, limit}; the metaobject shape is metaobjects.md's.
• Errors: 404 not_found (no such app record type, or a private one).
• SDK: apps.listAppRecords(client, appKey, recordType, query?) composes the type; apps.getAppRecord(client, appKey, recordType, handle) reads one with references resolved.
• Components: the app's own storefront component, under apps/<key>/ in the storefront project.
• Settings: the app's records are edited in the admin under Apps, the app, its records screen.

# A record type nobody deployed is a 404, the same answer a private one gives.
STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
  "$BASE/api/store/metaobjects/doc-no-app-$RUN.location" -H "x-client-id: $CLIENT_ID")
test "$STATUS" = 404

import { listAppRecords } from "@cartbase/storefront/api/apps"

const { metaobjects: locations } = await listAppRecords(client, "store-locator", "location", { limit: 100 })
for (const location of locations) {
  const city = location.fields.find((f) => f.key === "city")?.value
}