fix: Correct code sample errors and add tab formatting to CI (#1105)

* fix: Correct syntax errors and typos in hand-written code samples across guides

Fixes 19 issues found during a code sample audit:
- Wrong capability flag in quickstart cURL (can_remotely_lock → can_remotely_unlock)
- Wrong cURL endpoints (access_methods/get → access_grants/create, devices/list → events/list)
- Extra '>' in cURL URL (customer-portals)
- Python syntax using Ruby-style ':' instead of '=' for kwargs (mobile-key-quick-start)
- Wrong PHP class name (SeamSeamClient → Seam\SeamClient in nuki-locks)
- Wrong C# method name (SystemsAcs.List → Acs.Systems.List)
- Malformed JSON using '=' instead of ':' (filtering-connect-webviews)
- JS object literal using '=' instead of ':' (hospitality guides)
- JS variable name mismatch (connectedAccounts vs connected_accounts)
- Missing JSON commas in output examples (multiple files)
- Stray spaces before array index [0] (nest-thermostats)
- Ruby placeholder using JS comment syntax (// → #)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: Add format-code-sample-tabs to CI format workflow

Adds a codegen script that auto-fixes code sample tab order and titles
in guide and brand-guide markdown files. Runs as part of the Format CI
workflow, which auto-commits fixes on non-main branches.

The canonical tab order and title mapping are defined in a shared module
(codegen/lib/code-sample-tab-order.ts), imported by both the API
reference codegen and the tab formatter — single source of truth.

The script:
- Reorders tabs to match API reference canonical order
  (JavaScript → cURL → Python → Ruby → PHP → C# → Java → Go → Seam CLI)
- Normalizes tab titles ("cURL (bash)" → "cURL", "Javascript" → "JavaScript")
- Ensures GitBook tab syncing works across all code blocks on a page

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: Format code

* fix: Include api-reference source files in tab formatter scope

Adds codegen/source/docs/api-reference/ to the format-code-sample-tabs
scan paths so hand-written api-reference pages (authentication.md,
pagination.md) also get their tabs normalized. Fixes 6 remaining
"cURL (bash)" → "cURL" instances.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: Generate docs

* fix: Fix = vs : in JS/Ruby/PHP named args and missing PHP comma

Fixes acs_system_ids using = instead of : in JavaScript object literals,
Ruby keyword arguments, and PHP named parameters across encoder-related
code samples. Also fixes a missing comma in PHP code in
mapping-your-resources-to-seam-resources.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Seam Bot <seambot@getseam.com>

Author: 3 people

.github/workflows/format.yml

@@ -29,6 +29,8 @@ jobs:
           passphrase: ${{ secrets.GPG_PASSPHRASE }}
       - name: Setup
         uses: ./.github/actions/setup
+      - name: Format code sample tabs
+        run: npm run format-code-sample-tabs
       - name: Format
         run: npm run format
       - name: Commit

codegen/format-code-sample-tabs.ts

@@ -0,0 +1,78 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { globSync } from 'glob'
+
+import { tabTitleFixes, tabTitleOrder } from './lib/code-sample-tab-order.js'
+
+const tabsBlockPattern = /\{%\s*tabs\s*%\}[\s\S]*?\{%\s*endtabs\s*%\}/g
+
+const tabPattern =
+  /\{%\s*tab\s+title="([^"]+)"\s*%\}([\s\S]*?)\{%\s*endtab\s*%\}/g
+
+function canonicalIndex(title: string): number {
+  const normalized = tabTitleFixes[title] ?? title
+  return tabTitleOrder.get(normalized) ?? tabTitleOrder.size + 1
+}
+
+function formatTabsBlock(block: string): { result: string; changed: boolean } {
+  const tabs: Array<{ title: string; content: string }> = []
+  for (const match of block.matchAll(tabPattern)) {
+    tabs.push({ title: match[1] ?? '', content: match[2] ?? '' })
+  }
+
+  if (tabs.length < 2) return { result: block, changed: false }
+
+  const originalTitles = tabs.map((t) => t.title)
+  const sorted = [...tabs].sort(
+    (a, b) => canonicalIndex(a.title) - canonicalIndex(b.title),
+  )
+  const sortedTitles = sorted.map((t) => t.title)
+  const needsRename = originalTitles.some((t) => t in tabTitleFixes)
+  const needsReorder = originalTitles.some((t, i) => t !== sortedTitles[i])
+
+  if (!needsReorder && !needsRename) return { result: block, changed: false }
+
+  const lines = ['{% tabs %}']
+  for (const tab of sorted) {
+    const title = tabTitleFixes[tab.title] ?? tab.title
+    lines.push(`{% tab title="${title}" %}`)
+    lines.push(tab.content.trimEnd())
+    lines.push('{% endtab %}')
+    lines.push('')
+  }
+  while (lines.at(-1) === '') lines.pop()
+  lines.push('{% endtabs %}')
+
+  return { result: lines.join('\n'), changed: true }
+}
+
+const dirs = [
+  'docs/guides',
+  'docs/brand-guides',
+  'codegen/source/docs/api-reference',
+]
+const files = dirs.flatMap((dir) => globSync(join(dir, '**/*.md')))
+
+let totalChanged = 0
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf-8')
+  let changed = false
+
+  const updated = content.replace(tabsBlockPattern, (block) => {
+    const { result, changed: blockChanged } = formatTabsBlock(block)
+    if (blockChanged) changed = true
+    return result
+  })
+
+  if (changed) {
+    writeFileSync(file, updated)
+    totalChanged++
+  }
+}
+
+if (totalChanged > 0) {
+  // eslint-disable-next-line no-console
+  console.log(`Formatted tabs in ${String(totalChanged)} file(s).`)
+}

codegen/lib/code-sample-tab-order.ts

@@ -0,0 +1,47 @@
+import type { SdkName } from '@seamapi/blueprint'
+
+/**
+ * Canonical tab order for code samples across all documentation.
+ * Used by the API reference codegen (api-endpoint.ts) and the
+ * format-code-sample-tabs script to keep guide tabs in sync.
+ */
+export const supportedSdkOrder: SdkName[] = [
+  'javascript',
+  'curl',
+  'python',
+  'ruby',
+  'php',
+  'csharp',
+  'java',
+  'go',
+  'seam_cli',
+]
+
+/**
+ * Maps SdkName values to their canonical display titles as used in
+ * GitBook tab headers. Sourced from @seamapi/blueprint CodeSample titles.
+ */
+export const sdkDisplayTitle: Record<SdkName, string> = {
+  javascript: 'JavaScript',
+  curl: 'cURL',
+  python: 'Python',
+  ruby: 'Ruby',
+  php: 'PHP',
+  csharp: 'C#',
+  java: 'Java',
+  go: 'Go',
+  seam_cli: 'Seam CLI',
+}
+
+/** Reverse lookup: display title → canonical index. */
+export const tabTitleOrder: Map<string, number> = new Map(
+  supportedSdkOrder.map((sdk, i) => [sdkDisplayTitle[sdk], i]),
+)
+
+/** Known non-canonical title variants that should be normalized. */
+export const tabTitleFixes: Record<string, string> = {
+  'cURL (bash)': 'cURL',
+  Bash: 'cURL',
+  Javascript: 'JavaScript',
+  javascript: 'JavaScript',
+}

codegen/lib/layout/api-endpoint.ts

@@ -13,6 +13,7 @@ import type {
 } from '@seamapi/blueprint'
 import { capitalCase } from 'change-case'
 
+import { supportedSdkOrder } from '../code-sample-tab-order.js'
 import type { PathMetadata } from '../path-metadata.js'
 import {
   type ApiRouteResource,
@@ -23,14 +24,18 @@ import {
   resourceSampleFilter,
 } from './api-route.js'
 
-const supportedSdks: SdkName[] = [
+const apiReferenceSdks = new Set<SdkName>([
   'javascript',
   'curl',
   'python',
   'ruby',
   'php',
   'seam_cli',
-]
+])
+
+const supportedSdks = supportedSdkOrder.filter((sdk) =>
+  apiReferenceSdks.has(sdk),
+)
 
 export interface ApiEndpointLayoutContext {
   description: string

codegen/source/docs/api-reference/authentication.md

@@ -13,32 +13,38 @@ $ export SEAM_API_KEY=seam_test2bMS_94SrGUXuNR2JmJkjtvBQDg5c
 Next, run the following code to confirm that you are correctly authenticated:
 
 {% tabs %}
-{% tab title="Python" %}
+{% tab title="JavaScript" %}
+
 **Code:**
 
-```python
-from seam import Seam
+```javascript
+import { Seam } from "seam";
 
-seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.
+const seam = new Seam(); // Seam automatically uses your exported SEAM_API_KEY.
 
-workspace = seam.workspaces.get()
-pprint(workspace)
+const checkAuth = async () => {
+  const workspace = await seam.workspaces.get();
+  console.log(workspace);
+}
+
+checkAuth();
 ```
 
 **Output:**
 
-```
-Workspace(
-  workspace_id='00000000-0000-0000-0000-000000000000',
-  name='Sandbox',
-  company_name='Acme',
-  connect_partner_name='Acme',
-  is_sandbox=True
-)
+```json
+{
+  workspace_id: '00000000-0000-0000-0000-000000000000',
+  name: 'Sandbox',
+  company_name: 'Acme',
+  connect_partner_name: 'Acme',
+  is_sandbox": true
+} 
 ```
 {% endtab %}
 
-{% tab title="cURL (bash)" %}
+{% tab title="cURL" %}
+
 **Code:**
 
 ```bash
@@ -66,36 +72,34 @@ curl -X 'POST' \
 ```
 {% endtab %}
 
-{% tab title="JavaScript" %}
-**Code:**
+{% tab title="Python" %}
 
-```javascript
-import { Seam } from "seam";
+**Code:**
 
-const seam = new Seam(); // Seam automatically uses your exported SEAM_API_KEY.
+```python
+from seam import Seam
 
-const checkAuth = async () => {
-  const workspace = await seam.workspaces.get();
-  console.log(workspace);
-}
+seam = Seam()  # Seam automatically uses your exported SEAM_API_KEY.
 
-checkAuth();
+workspace = seam.workspaces.get()
+pprint(workspace)
 ```
 
 **Output:**
 
-```json
-{
-  workspace_id: '00000000-0000-0000-0000-000000000000',
-  name: 'Sandbox',
-  company_name: 'Acme',
-  connect_partner_name: 'Acme',
-  is_sandbox": true
-} 
+```
+Workspace(
+  workspace_id='00000000-0000-0000-0000-000000000000',
+  name='Sandbox',
+  company_name='Acme',
+  connect_partner_name='Acme',
+  is_sandbox=True
+)
 ```
 {% endtab %}
 
 {% tab title="Ruby" %}
+
 **Code:**
 
 ```ruby
@@ -123,6 +127,7 @@ puts workspace.inspect
 {% endtab %}
 
 {% tab title="PHP" %}
+
 **Code:**
 
 ```php
@@ -150,6 +155,7 @@ echo json_encode($workspace, JSON_PRETTY_PRINT);
 {% endtab %}
 
 {% tab title="C#" %}
+
 **Code:**
 
 ```csharp
@@ -174,7 +180,4 @@ Console.WriteLine(workspace);
 }
 ```
 {% endtab %}
-
-
-
 {% endtabs %}