chore(docs): update documentation

Signed-off-by: Frederik Bußmann <frederik@bussmann.io>

Author: freb97

docs/content/1.getting-started/4.usage.md

@@ -304,6 +304,48 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
+## Outside of Nuxt
+
+The composables above resolve their configuration from the runtime config, so they only work inside a Nuxt app.
+For Node scripts that run outside the Nuxt runtime the module also exports the
+client factories directly:
+
+```ts [scripts/export-products.ts]
+import { createAdminClient } from '@nuxtjs/shopify'
+
+const admin = createAdminClient({
+  name: 'quickstart-abcd1234',
+  clients: {
+    admin: {
+      clientId: process.env.SHOPIFY_CLIENT_ID!,
+      clientSecret: process.env.SHOPIFY_CLIENT_SECRET!,
+    },
+  },
+})
+
+const { data } = await admin.request(`#graphql
+  query GetProducts {
+    products(first: 10) {
+      nodes {
+        id
+        title
+      }
+    }
+  }
+`)
+
+console.log(flattenConnection(data?.products))
+```
+
+`createStorefrontClient`, `createCustomerAccountClient` and `createShopifyClient` are exported the same way.
+Access tokens are resolved exactly as they are inside Nuxt, so an admin client configured with a client ID and
+secret performs the OAuth token exchange for you.
+
+::warning
+These factories are meant for Node-side code. Inside your app, keep using the auto-imported composables - they
+wire up proxying, caching, tracking and the Nuxt hooks that the bare factories do not.
+::
+
 ## Fragments
 
 When using the Shopify GraphQL APIs, it's common to reuse fragments across multiple queries and mutations.
@@ -549,3 +591,45 @@ export default defineNuxtConfig({
 ::note
 See the [module configuration reference](/essentials/configuration).
 ::
+
+## Utilities
+
+Alongside the clients, the module auto-imports a few helpers for working with Shopify responses.
+They are available on both the client and the server.
+
+### flattenConnection
+
+Shopify returns paginated data as a connection with `edges` and `nodes`. `flattenConnection` turns either shape
+into a plain array, so you do not have to map over `edges` yourself:
+
+```vue [app/pages/products.vue]
+<script setup lang="ts">
+const { data } = await useStorefrontData('products', `#graphql
+  query GetProducts {
+    products(first: 10) {
+      nodes {
+        id
+        title
+      }
+    }
+  }
+`)
+
+const products = computed(() => flattenConnection(data.value?.products))
+</script>
+```
+
+It returns an empty array when the connection is `null` or `undefined`, so the result is always safe to iterate.
+
+### parseGid
+
+Shopify identifies every record with a global ID such as `gid://shopify/Product/1234567890`.
+`parseGid` extracts the numeric ID from it, which is useful for URLs, analytics payloads, or third-party systems:
+
+```ts
+const id = parseGid('gid://shopify/Product/1234567890') // '1234567890'
+```
+
+::warning
+`parseGid` throws when the value is not a valid global ID. Guard the call if the ID may be missing or user-supplied.
+::

docs/content/2.essentials/2.configuration.md

@@ -230,6 +230,10 @@ Configure one or more API clients:
   Client ID for customer account API requests
   :::
 
+  :::field{name="apiUrl" type="string"}
+  Customer Account API endpoint. Resolved automatically at build time, set this to override.
+  :::
+
   :::field{name="clientSecret" type="string"}
   Client secret for confidential clients. When set, the OAuth token exchange is authenticated with the secret instead of PKCE - server-side only, optional
   :::

docs/content/2.essentials/4.customer-account.md

@@ -122,6 +122,22 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
+To end a session from your own code use the auto-imported `clearCustomerAccountSession` helper.
+It clears the session cookie and removes stored tokens when an external `tokenStorage` is configured:
+
+```ts [~/server/api/sign-out.ts]
+export default defineEventHandler(async (event) => {
+  await clearCustomerAccountSession(event)
+
+  return { ok: true }
+})
+```
+
+::note
+This only clears the local session. To also sign the customer out of Shopify, send them to the configured
+`logoutURL` instead, which performs the OpenID Connect logout.
+::
+
 Once the user is authenticated, you can use the `useCustomerAccount` and `useCustomerAccountData` composables
 to fetch customer data from the Customer Account API.
 

docs/content/2.essentials/7.caching.md

@@ -203,9 +203,16 @@ Proxy caching is persistent and done on the server side.
   :::
 ::
 
+::warning
+The proxy cache is shared by every visitor. The cache key is derived from the query, the variables and the cache
+tier only. Never assign a proxy cache tier to personalized queries (carts, customer data, buyer-specific pricing),
+or one visitor's response will be served to another. The client cache is per browser session and is not affected
+by this.
+::
+
 ::warning
 Known limitations:
-* Nitro will currently deliver stale requests even if `staleMaxAge` has been reached: [issue](https://github.com/nitrojs/nitro/issues/2164).
+* In Nitro v2, stale requests may be delivered even if `staleMaxAge` has been reached: [issue](https://github.com/nitrojs/nitro/issues/2164).
 ::
 
 ### Server Side