@pikku/openapi-parser 0.12.15 → 0.12.17

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @pikku/openapi-parser
 
+## 0.12.17
+
+### Patch Changes
+
+- a7b26c5: rename the inspected declarations to `define*`: `wireScope` → `defineScope`, `wireSecret` → `defineSecret`, `wireVariable` → `defineVariable`, `wireCredential` → `defineCredential`
+
+  `wire*` meant two unrelated things. A transport wiring attaches a function to
+  something that can invoke it — `wireHTTP`, `wireChannel`, `wireScheduler`,
+  `wireQueueWorker` and the rest — and the thing it wires runs. These four wire
+  nothing: they are no-ops that exist only so the call typechecks, they are
+  tree-shaken out of the build, and their whole job is to be found by the
+  inspector's AST pass and turned into a type union. One word for both left the
+  declaration reading like a registration with a runtime.
+
+  So the vocabulary splits: **`wire*` is a transport, `define*` is an inspected
+  declaration.**
+
+  ```ts
+  import { defineScope } from '@pikku/core/scope'
+  import { defineSecret } from '@pikku/core/secret'
+  import { defineVariable } from '@pikku/core/variable'
+  import { defineCredential } from '@pikku/core/credential'
+
+  defineScope({ admin: { scopes: { invoices: { scopes: { create: {} } } } } })
+  ```
+
+  **Breaking:** no alias is kept. Rename the four call sites; the module subpaths
+  (`@pikku/core/scope`, `/secret`, `/variable`) are unchanged.
+
+  The inspector matches these by identifier text, so a stale `wire*` call is not a
+  type error — it is silently not extracted, and the generated union comes back
+  empty. That fails as "this scope isn't declared" on code that was fine a moment
+  ago, nowhere near the declaration. Grep for the old names rather than trusting a
+  clean build.
+
+  An addon published with `.pikku` output generated before this release re-exports
+  `wireSecret` from `@pikku/core/secret` and will not typecheck against this core
+  until it is rebuilt and republished.
+
+## 0.12.16
+
+### Patch Changes
+
+- 9f0d0eb: Migrate the `--oauth` addon scaffold off `OAuth2Client`. A scaffolded OAuth2
+  addon service used to construct `new OAuth2Client(config, appCredentialSecretId,
+secrets)` and do its own token exchange/refresh — the responsibility better-auth
+  now owns via the credential service. The `pikku new addon --oauth` scaffold (and
+  the OpenAPI `--openapi` generator) now emit a service that receives a ready
+  access token: `services.ts` uses `createWireServices` + `wire.getCredential<{
+accessToken: string }>(name)` and the service does a plain `fetch` with
+  `Authorization: Bearer ${accessToken}`, matching the existing per-user
+  bearer/apikey credential scaffold. With no remaining consumers, `OAuth2Client`
+  (`@pikku/core/oauth2`) and its test are removed; the `./oauth2` export keeps the
+  `OAuth2AppCredential` / `OAuth2Token` types.
+- 8601505: Make `wireCredential` the single source of truth for an addon's OAuth2 config: `pikku-credentials.gen.ts` exports `CREDENTIAL_OAUTH2_CONFIGS`, generated services import from it, the OpenAPI importer emits a `wireCredential`, and the inspector now extracts `oauth2.additionalParams`.
+
 ## 0.12.15
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 - present Yasser Fadl and Pikku contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @pikku/openapi-parser
+
+Parses OpenAPI specs into a normalised shape and generates Pikku addon code
+from them — operations, parameters, error responses and security schemes.
+
+## Install
+
+```bash
+npm install -D @pikku/openapi-parser
+```
+
+## Usage
+
+```typescript
+import { parseOpenAPISpec, computeContractHash } from '@pikku/openapi-parser'
+
+const spec = await parseOpenAPISpec(specPath)
+const hash = computeContractHash(spec)
+```
+
+The contract hash lets generated addons detect when an upstream spec changed.
+
+## Docs
+
+https://pikku.dev/docs

package/dist/codegen.js

@@ -62,7 +62,8 @@ function humanDescription(parsed) {
     if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
         return capitalize(summary);
     }
-    return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`;
+    return (humanizeOperationId(parsed.operationId) ??
+        `${parsed.method.toUpperCase()} ${parsed.path}`);
 }
 function getErrorClassesForResponses(errorResponses) {
     const classes = [];
@@ -293,10 +294,15 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
     }
     // Generate index.ts with all exports
     files['src/index.ts'] = generateIndexFile(functionExports, {
-        upstreamAuth: upstreamAuthExport ? { name, export: upstreamAuthExport } : undefined,
+        upstreamAuth: upstreamAuthExport
+            ? { name, export: upstreamAuthExport }
+            : undefined,
     });
     // Generate typed API service class with route map
     files[`src/${name}-api.service.ts`] = generateServiceFile(spec, opPairs, vars, flags);
+    if (flags.oauth || flags.credential === 'oauth2') {
+        files[`src/${name}.credential.ts`] = generateCredentialFile(spec, vars);
+    }
     // Generate variable file for BASE_URL
     files[`src/${name}.variable.ts`] = generateVariableFile(spec, vars);
     return files;
@@ -935,8 +941,8 @@ function generateServiceFile(spec, opPairs, vars, flags) {
         // Per-user credential: no special imports needed, creds passed via constructor
     }
     else if (flags.oauth || flags.credential === 'oauth2') {
-        lines.push("import { OAuth2Client } from '@pikku/core/oauth2'");
-        lines.push("import type { TypedSecretService } from '#pikku/secrets/pikku-secrets.gen.js'");
+        // OAuth2: the access token is resolved via the credential service and passed
+        // via the constructor — no special imports needed.
     }
     else if (flags.secret) {
         lines.push(`import type { ${pascalName}Secrets } from './${name}.secret.js'`);
@@ -946,23 +952,6 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     }
     lines.push(`import type { TypedVariablesService } from '#pikku/variables/pikku-variables.gen.js'`);
     lines.push('');
-    if (flags.oauth) {
-        // Use OAuth2 details from spec if available
-        const oauthScheme = Object.values(spec.securitySchemes).find((s) => s.type === 'oauth2');
-        const authUrl = oauthScheme?.flows?.authorizationUrl ??
-            'https://example.com/oauth2/authorize';
-        const tokenUrl = oauthScheme?.flows?.tokenUrl ?? 'https://example.com/oauth2/token';
-        const scopes = oauthScheme?.flows?.scopes
-            ? Object.keys(oauthScheme.flows.scopes)
-            : ['read', 'write'];
-        lines.push(`export const ${screamingName}_OAUTH2_CONFIG = {`);
-        lines.push(`  tokenSecretId: '${screamingName}_TOKENS',`);
-        lines.push(`  authorizationUrl: ${JSON.stringify(authUrl)},`);
-        lines.push(`  tokenUrl: ${JSON.stringify(tokenUrl)},`);
-        lines.push(`  scopes: ${JSON.stringify(scopes)},`);
-        lines.push('}');
-        lines.push('');
-    }
     // Generate route map from parsed operations
     const routes = {};
     for (const { parsed } of opPairs) {
@@ -1007,15 +996,9 @@ function generateServiceFile(spec, opPairs, vars, flags) {
         lines.push('  }');
     }
     else if (flags.oauth || flags.credential === 'oauth2') {
-        lines.push('  private oauth: OAuth2Client');
         lines.push('');
-        lines.push(`  constructor(secrets: TypedSecretService, variables: TypedVariablesService) {`);
+        lines.push(`  constructor(private creds: { accessToken: string }, variables: TypedVariablesService) {`);
         lines.push(`    this.baseUrl = variables.get('${screamingName}_BASE_URL') as string`);
-        lines.push('    this.oauth = new OAuth2Client(');
-        lines.push(`      ${screamingName}_OAUTH2_CONFIG,`);
-        lines.push(`      '${screamingName}_APP_CREDENTIALS',`);
-        lines.push('      secrets');
-        lines.push('    )');
         lines.push('  }');
     }
     else if (flags.secret) {
@@ -1122,7 +1105,9 @@ function generateServiceFile(spec, opPairs, vars, flags) {
         lines.push('    })');
     }
     else if (flags.oauth || flags.credential === 'oauth2') {
-        lines.push('    const response = await this.oauth.request(url.toString(), {');
+        lines.push('    headers.Authorization = `Bearer ${this.creds.accessToken}`');
+        lines.push('');
+        lines.push('    const response = await fetch(url.toString(), {');
         lines.push('      method,');
         lines.push('      headers,');
         lines.push('      body: body ? JSON.stringify(body) : undefined,');
@@ -1187,6 +1172,63 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     lines.push('');
     return lines.join('\n');
 }
+function generateCredentialFile(spec, vars) {
+    const { camelName, screamingName } = vars;
+    const displayName = vars.displayName.replace(/'/g, '');
+    const description = vars.description.replace(/'/g, '');
+    const oauthScheme = Object.values(spec.securitySchemes).find((s) => s.type === 'oauth2');
+    const authorizationUrl = oauthScheme?.flows?.authorizationUrl;
+    const tokenUrl = oauthScheme?.flows?.tokenUrl;
+    const scopes = oauthScheme?.flows?.scopes
+        ? Object.keys(oauthScheme.flows.scopes)
+        : ['read', 'write'];
+    const lines = [];
+    lines.push("import { z } from 'zod'");
+    lines.push("import { defineCredential } from '@pikku/core/credential'");
+    lines.push("import { defineSecret } from '@pikku/core/secret'");
+    lines.push('');
+    lines.push(`export const ${camelName}TokenSchema = z.object({`);
+    lines.push('  accessToken: z.string(),');
+    lines.push('  refreshToken: z.string().optional(),');
+    lines.push('})');
+    lines.push('');
+    lines.push(`export const ${camelName}OAuthAppSchema = z.object({`);
+    lines.push("  clientId: z.string().describe('OAuth2 app client ID'),");
+    lines.push("  clientSecret: z.string().describe('OAuth2 app client secret'),");
+    lines.push('})');
+    lines.push('');
+    if (!authorizationUrl || !tokenUrl) {
+        lines.push('// TODO: this spec declares no oauth2 flow URLs, so the placeholder(s)');
+        lines.push(`// below are not real. Replace them with ${displayName}'s endpoints —`);
+        lines.push('// OAuth will fail against example.com.');
+    }
+    // oauth2 must stay an inline object literal: the inspector reads it via AST
+    // (add-credential.ts) and silently drops a config behind an identifier.
+    lines.push('defineCredential({');
+    lines.push(`  name: '${camelName}',`);
+    lines.push(`  displayName: '${displayName}',`);
+    lines.push(`  description: '${description}',`);
+    lines.push(`  type: 'wire',`);
+    lines.push(`  schema: ${camelName}TokenSchema,`);
+    lines.push('  oauth2: {');
+    lines.push(`    appCredentialSecretId: '${screamingName}_OAUTH_APP',`);
+    lines.push(`    tokenSecretId: '${screamingName}_OAUTH_TOKENS',`);
+    lines.push(`    authorizationUrl: ${JSON.stringify(authorizationUrl ?? 'https://example.com/oauth2/authorize')},`);
+    lines.push(`    tokenUrl: ${JSON.stringify(tokenUrl ?? 'https://example.com/oauth2/token')},`);
+    lines.push(`    scopes: ${JSON.stringify(scopes)},`);
+    lines.push('  },');
+    lines.push('})');
+    lines.push('');
+    lines.push('defineSecret({');
+    lines.push(`  name: '${camelName}OAuthApp',`);
+    lines.push(`  displayName: '${displayName} OAuth App',`);
+    lines.push(`  description: 'OAuth2 app credentials for ${displayName}',`);
+    lines.push(`  secretId: '${screamingName}_OAUTH_APP',`);
+    lines.push(`  schema: ${camelName}OAuthAppSchema,`);
+    lines.push('})');
+    lines.push('');
+    return lines.join('\n');
+}
 function generateVariableFile(spec, vars) {
     const { camelName, screamingName } = vars;
     const displayName = vars.displayName.replace(/'/g, '');
@@ -1194,7 +1236,7 @@ function generateVariableFile(spec, vars) {
     const defaultUrl = serverUrls[0];
     const lines = [];
     lines.push("import { z } from 'zod'");
-    lines.push("import { wireVariable } from '@pikku/core/variable'");
+    lines.push("import { defineVariable } from '@pikku/core/variable'");
     lines.push('');
     const schemaVarName = `${camelName}BaseUrlSchema`;
     if (serverUrls.length > 0) {
@@ -1205,7 +1247,7 @@ function generateVariableFile(spec, vars) {
         lines.push(`export const ${schemaVarName} = z.string().describe('Base URL for the ${displayName} API')`);
     }
     lines.push('');
-    lines.push(`wireVariable({`);
+    lines.push(`defineVariable({`);
     lines.push(`  name: '${screamingName}_BASE_URL',`);
     lines.push(`  displayName: '${displayName} Base URL',`);
     lines.push(`  description: 'The base URL for the ${displayName} API.',`);

package/dist/naming.js

@@ -2,18 +2,22 @@
  * Derives function/method names from HTTP method + path.
  * Uses operationId when available, otherwise generates from path segments.
  */
-/** JavaScript/TypeScript reserved words that cannot be used as identifiers */
+/**
+ * Words that are illegal as a `const`/binding identifier in a strict-mode module
+ * (generated code is always ESM). Contextual keywords that are only special in a
+ * specific position — `get`/`set` (getters), `type`/`as`/`from`/`of` (type & import
+ * syntax), `any`/`number`/`object`/`string`/`symbol`/`declare`/`module`/`require`
+ * (type positions), and the legacy ES3 future-reserved words (`byte`, `char`, `int`,
+ * `long`, `short`, `float`, `double`, `boolean`, `goto`, `native`, `synchronized`,
+ * `transient`, `volatile`, `abstract`, `final`) — are all valid binding names and
+ * deliberately excluded, so `sheets.spreadsheets.get` stays `get`, not `_get`.
+ */
 const JS_RESERVED_WORDS = new Set([
-    // ECMAScript reserved words
-    'abstract',
     'arguments',
     'await',
-    'boolean',
     'break',
-    'byte',
     'case',
     'catch',
-    'char',
     'class',
     'const',
     'continue',
@@ -21,29 +25,22 @@ const JS_RESERVED_WORDS = new Set([
     'default',
     'delete',
     'do',
-    'double',
     'else',
     'enum',
     'eval',
     'export',
     'extends',
     'false',
-    'final',
     'finally',
-    'float',
     'for',
     'function',
-    'goto',
     'if',
     'implements',
     'import',
     'in',
     'instanceof',
-    'int',
     'interface',
     'let',
-    'long',
-    'native',
     'new',
     'null',
     'package',
@@ -51,40 +48,21 @@ const JS_RESERVED_WORDS = new Set([
     'protected',
     'public',
     'return',
-    'short',
     'static',
     'super',
     'switch',
-    'synchronized',
     'this',
     'throw',
     'throws',
-    'transient',
     'true',
     'try',
     'typeof',
     'undefined',
     'var',
     'void',
-    'volatile',
     'while',
     'with',
     'yield',
-    // TypeScript additional reserved words in strict mode
-    'as',
-    'any',
-    'declare',
-    'get',
-    'module',
-    'require',
-    'number',
-    'object',
-    'set',
-    'string',
-    'symbol',
-    'type',
-    'from',
-    'of',
 ]);
 /**
  * Ensure a name is a valid JS/TS identifier:
@@ -203,6 +181,35 @@ const METHOD_PREFIXES = {
     patch: 'update',
     delete: 'delete',
 };
+/**
+ * Find the longest shared leading run of dot-separated operationId segments,
+ * always leaving at least one trailing segment on every operation. Only applies
+ * when every operation has a dotted operationId (e.g. Google's
+ * `sheets.spreadsheets.values.get`), so specs whose ids are camelCase or absent
+ * are left untouched. The shared prefix is redundant with the addon namespace,
+ * so stripping it turns `sheetsSpreadsheetsValuesGet` into `valuesGet`.
+ */
+function commonOperationIdPrefix(operations) {
+    if (operations.length < 2) {
+        return [];
+    }
+    if (!operations.every((op) => op.operationId && op.operationId.includes('.'))) {
+        return [];
+    }
+    const segmented = operations.map((op) => op.operationId.split('.'));
+    const minLen = Math.min(...segmented.map((s) => s.length));
+    const prefix = [];
+    for (let i = 0; i < minLen - 1; i++) {
+        const seg = segmented[0][i];
+        if (segmented.every((s) => s[i] === seg)) {
+            prefix.push(seg);
+        }
+        else {
+            break;
+        }
+    }
+    return prefix;
+}
 /**
  * Generate function names for a list of operations.
  * Handles collision detection and auto-deduplication.
@@ -215,10 +222,14 @@ export function generateOperationNames(operations, commonPrefix) {
     // only in casing (e.g. userGetOauth2Application vs userGetOAuth2Application)
     // would produce files that collide on disk.
     const usedNamesLower = new Map();
+    const opIdPrefix = commonOperationIdPrefix(operations);
     for (const op of operations) {
         let name;
         if (op.operationId) {
-            name = fromOperationId(op.operationId);
+            const opId = opIdPrefix.length
+                ? op.operationId.split('.').slice(opIdPrefix.length).join('.')
+                : op.operationId;
+            name = fromOperationId(opId);
         }
         else {
             name = deriveNameFromPath(op.method, op.path, commonPrefix);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/openapi-parser",
-  "version": "0.12.15",
+  "version": "0.12.17",
   "description": "OpenAPI spec parser and code generator for Pikku",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/codegen.test.ts

@@ -801,7 +801,8 @@ describe('function description synthesis', () => {
       secret: false,
       mcp: true,
     })
-    const funcFile = files['src/functions/contactsControllerGetContacts.function.ts']
+    const funcFile =
+      files['src/functions/contactsControllerGetContacts.function.ts']
     assert.ok(funcFile, 'function file should exist')
     assert.ok(
       funcFile.includes('description: "Contacts get contacts"'),
@@ -812,7 +813,9 @@ describe('function description synthesis', () => {
 
   test('falls back to "METHOD /path" when operationId is absent', () => {
     const spec = makeSpec({
-      operations: [makeOp({ operationId: undefined, method: 'get', path: '/health' })],
+      operations: [
+        makeOp({ operationId: undefined, method: 'get', path: '/health' }),
+      ],
     })
 
     const files = generateAddonFromOpenAPI(spec, makeVars(), {
@@ -830,7 +833,10 @@ describe('function description synthesis', () => {
   test('prefers the spec description over synthesis', () => {
     const spec = makeSpec({
       operations: [
-        makeOp({ operationId: 'getPet', description: 'Fetch a single pet by id' }),
+        makeOp({
+          operationId: 'getPet',
+          description: 'Fetch a single pet by id',
+        }),
       ],
     })
 

package/src/codegen.ts

@@ -105,7 +105,10 @@ function humanDescription(parsed: ParsedOperation): string {
   if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
     return capitalize(summary)
   }
-  return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`
+  return (
+    humanizeOperationId(parsed.operationId) ??
+    `${parsed.method.toUpperCase()} ${parsed.path}`
+  )
 }
 
 function getErrorClassesForResponses(
@@ -433,7 +436,9 @@ export function generateAddonFromOpenAPI(
 
   // Generate index.ts with all exports
   files['src/index.ts'] = generateIndexFile(functionExports, {
-    upstreamAuth: upstreamAuthExport ? { name, export: upstreamAuthExport } : undefined,
+    upstreamAuth: upstreamAuthExport
+      ? { name, export: upstreamAuthExport }
+      : undefined,
   })
 
   // Generate typed API service class with route map
@@ -444,6 +449,10 @@ export function generateAddonFromOpenAPI(
     flags
   )
 
+  if (flags.oauth || flags.credential === 'oauth2') {
+    files[`src/${name}.credential.ts`] = generateCredentialFile(spec, vars)
+  }
+
   // Generate variable file for BASE_URL
   files[`src/${name}.variable.ts`] = generateVariableFile(spec, vars)
 
@@ -1075,9 +1084,7 @@ function generateUpstreamAuthFile(
   )
   lines.push('}')
   lines.push('')
-  lines.push(
-    `export interface ${pascalName}UpstreamCredentials {`
-  )
+  lines.push(`export interface ${pascalName}UpstreamCredentials {`)
   lines.push('  email?: string')
   lines.push('  password?: string')
   lines.push('  apiKey?: string')
@@ -1098,18 +1105,16 @@ function generateUpstreamAuthFile(
     "  typeof value === 'string' && value ? value : typeof value === 'number' ? String(value) : undefined"
   )
   lines.push('')
-  lines.push('/** Decode a JWT payload without verifying — see file docblock. */')
+  lines.push(
+    '/** Decode a JWT payload without verifying — see file docblock. */'
+  )
   lines.push('const decodeJwtPayload = (token: string): unknown => {')
   lines.push("  const part = token.split('.')[1]")
   lines.push('  if (!part) return undefined')
   lines.push('  try {')
   lines.push("    const pad = part + '==='.slice((part.length + 3) % 4)")
-  lines.push(
-    "    const bin = atob(pad.replace(/-/g, '+').replace(/_/g, '/'))"
-  )
-  lines.push(
-    '    const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0))'
-  )
+  lines.push("    const bin = atob(pad.replace(/-/g, '+').replace(/_/g, '/'))")
+  lines.push('    const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0))')
   lines.push('    return JSON.parse(new TextDecoder().decode(bytes))')
   lines.push('  } catch {')
   lines.push('    // Not a decodable JWT — caller treats it as missing claims.')
@@ -1156,7 +1161,9 @@ function generateUpstreamAuthFile(
   lines.push(
     `  const response = await fetch(\`\${baseUrl.replace(/\\/+$/, '')}${delegated.loginPath}\`, {`
   )
-  lines.push(`    method: ${JSON.stringify(delegated.loginMethod.toUpperCase())},`)
+  lines.push(
+    `    method: ${JSON.stringify(delegated.loginMethod.toUpperCase())},`
+  )
   lines.push('    headers,')
   lines.push(
     '    body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,'
@@ -1165,7 +1172,9 @@ function generateUpstreamAuthFile(
   lines.push('  if (!response.ok) return null')
   lines.push('')
   lines.push('  const data: unknown = await response.json()')
-  lines.push(`  const token = str(pick(data, ${JSON.stringify(delegated.tokenPath)}))`)
+  lines.push(
+    `  const token = str(pick(data, ${JSON.stringify(delegated.tokenPath)}))`
+  )
   lines.push('  if (!token) return null')
   lines.push('')
   if (claims.source === 'jwt') {
@@ -1178,7 +1187,9 @@ function generateUpstreamAuthFile(
   lines.push(
     `  const externalId = str(pick(claims, ${JSON.stringify(claims.externalId)}))`
   )
-  lines.push(`  const email = str(pick(claims, ${JSON.stringify(claims.email)}))`)
+  lines.push(
+    `  const email = str(pick(claims, ${JSON.stringify(claims.email)}))`
+  )
   lines.push('  if (!externalId || !email) return null')
   lines.push('')
   if (namePaths.length > 0) {
@@ -1254,10 +1265,8 @@ function generateServiceFile(
   if (flags.credential && flags.credential !== 'oauth2') {
     // Per-user credential: no special imports needed, creds passed via constructor
   } else if (flags.oauth || flags.credential === 'oauth2') {
-    lines.push("import { OAuth2Client } from '@pikku/core/oauth2'")
-    lines.push(
-      "import type { TypedSecretService } from '#pikku/secrets/pikku-secrets.gen.js'"
-    )
+    // OAuth2: the access token is resolved via the credential service and passed
+    // via the constructor — no special imports needed.
   } else if (flags.secret) {
     lines.push(
       `import type { ${pascalName}Secrets } from './${name}.secret.js'`
@@ -1275,29 +1284,6 @@ function generateServiceFile(
   )
   lines.push('')
 
-  if (flags.oauth) {
-    // Use OAuth2 details from spec if available
-    const oauthScheme = Object.values(spec.securitySchemes).find(
-      (s) => s.type === 'oauth2'
-    )
-    const authUrl =
-      oauthScheme?.flows?.authorizationUrl ??
-      'https://example.com/oauth2/authorize'
-    const tokenUrl =
-      oauthScheme?.flows?.tokenUrl ?? 'https://example.com/oauth2/token'
-    const scopes = oauthScheme?.flows?.scopes
-      ? Object.keys(oauthScheme.flows.scopes)
-      : ['read', 'write']
-
-    lines.push(`export const ${screamingName}_OAUTH2_CONFIG = {`)
-    lines.push(`  tokenSecretId: '${screamingName}_TOKENS',`)
-    lines.push(`  authorizationUrl: ${JSON.stringify(authUrl)},`)
-    lines.push(`  tokenUrl: ${JSON.stringify(tokenUrl)},`)
-    lines.push(`  scopes: ${JSON.stringify(scopes)},`)
-    lines.push('}')
-    lines.push('')
-  }
-
   // Generate route map from parsed operations
   const routes: Record<string, RouteInfo> = {}
   for (const { parsed } of opPairs) {
@@ -1359,19 +1345,13 @@ function generateServiceFile(
     )
     lines.push('  }')
   } else if (flags.oauth || flags.credential === 'oauth2') {
-    lines.push('  private oauth: OAuth2Client')
     lines.push('')
     lines.push(
-      `  constructor(secrets: TypedSecretService, variables: TypedVariablesService) {`
+      `  constructor(private creds: { accessToken: string }, variables: TypedVariablesService) {`
     )
     lines.push(
       `    this.baseUrl = variables.get('${screamingName}_BASE_URL') as string`
     )
-    lines.push('    this.oauth = new OAuth2Client(')
-    lines.push(`      ${screamingName}_OAUTH2_CONFIG,`)
-    lines.push(`      '${screamingName}_APP_CREDENTIALS',`)
-    lines.push('      secrets')
-    lines.push('    )')
     lines.push('  }')
   } else if (flags.secret) {
     lines.push('')
@@ -1399,9 +1379,7 @@ function generateServiceFile(
   lines.push('    path: string,')
   lines.push('    data?: unknown')
   lines.push('  ): Promise<T> {')
-  lines.push(
-    '    const input = data as Record<string, unknown> | undefined'
-  )
+  lines.push('    const input = data as Record<string, unknown> | undefined')
   if (flags.camelCase) {
     lines.push('    const rawData = input ? _toSnakeCase(input) : input')
   }
@@ -1500,9 +1478,9 @@ function generateServiceFile(
     lines.push('      body: body ? JSON.stringify(body) : undefined,')
     lines.push('    })')
   } else if (flags.oauth || flags.credential === 'oauth2') {
-    lines.push(
-      '    const response = await this.oauth.request(url.toString(), {'
-    )
+    lines.push('    headers.Authorization = `Bearer ${this.creds.accessToken}`')
+    lines.push('')
+    lines.push('    const response = await fetch(url.toString(), {')
     lines.push('      method,')
     lines.push('      headers,')
     lines.push('      body: body ? JSON.stringify(body) : undefined,')
@@ -1581,6 +1559,79 @@ function generateServiceFile(
   return lines.join('\n')
 }
 
+function generateCredentialFile(spec: ParsedSpec, vars: AddonVars): string {
+  const { camelName, screamingName } = vars
+  const displayName = vars.displayName.replace(/'/g, '')
+  const description = vars.description.replace(/'/g, '')
+
+  const oauthScheme = Object.values(spec.securitySchemes).find(
+    (s) => s.type === 'oauth2'
+  )
+  const authorizationUrl = oauthScheme?.flows?.authorizationUrl
+  const tokenUrl = oauthScheme?.flows?.tokenUrl
+  const scopes = oauthScheme?.flows?.scopes
+    ? Object.keys(oauthScheme.flows.scopes)
+    : ['read', 'write']
+
+  const lines: string[] = []
+  lines.push("import { z } from 'zod'")
+  lines.push("import { defineCredential } from '@pikku/core/credential'")
+  lines.push("import { defineSecret } from '@pikku/core/secret'")
+  lines.push('')
+  lines.push(`export const ${camelName}TokenSchema = z.object({`)
+  lines.push('  accessToken: z.string(),')
+  lines.push('  refreshToken: z.string().optional(),')
+  lines.push('})')
+  lines.push('')
+  lines.push(`export const ${camelName}OAuthAppSchema = z.object({`)
+  lines.push("  clientId: z.string().describe('OAuth2 app client ID'),")
+  lines.push("  clientSecret: z.string().describe('OAuth2 app client secret'),")
+  lines.push('})')
+  lines.push('')
+
+  if (!authorizationUrl || !tokenUrl) {
+    lines.push(
+      '// TODO: this spec declares no oauth2 flow URLs, so the placeholder(s)'
+    )
+    lines.push(
+      `// below are not real. Replace them with ${displayName}'s endpoints —`
+    )
+    lines.push('// OAuth will fail against example.com.')
+  }
+
+  // oauth2 must stay an inline object literal: the inspector reads it via AST
+  // (add-credential.ts) and silently drops a config behind an identifier.
+  lines.push('defineCredential({')
+  lines.push(`  name: '${camelName}',`)
+  lines.push(`  displayName: '${displayName}',`)
+  lines.push(`  description: '${description}',`)
+  lines.push(`  type: 'wire',`)
+  lines.push(`  schema: ${camelName}TokenSchema,`)
+  lines.push('  oauth2: {')
+  lines.push(`    appCredentialSecretId: '${screamingName}_OAUTH_APP',`)
+  lines.push(`    tokenSecretId: '${screamingName}_OAUTH_TOKENS',`)
+  lines.push(
+    `    authorizationUrl: ${JSON.stringify(authorizationUrl ?? 'https://example.com/oauth2/authorize')},`
+  )
+  lines.push(
+    `    tokenUrl: ${JSON.stringify(tokenUrl ?? 'https://example.com/oauth2/token')},`
+  )
+  lines.push(`    scopes: ${JSON.stringify(scopes)},`)
+  lines.push('  },')
+  lines.push('})')
+  lines.push('')
+  lines.push('defineSecret({')
+  lines.push(`  name: '${camelName}OAuthApp',`)
+  lines.push(`  displayName: '${displayName} OAuth App',`)
+  lines.push(`  description: 'OAuth2 app credentials for ${displayName}',`)
+  lines.push(`  secretId: '${screamingName}_OAUTH_APP',`)
+  lines.push(`  schema: ${camelName}OAuthAppSchema,`)
+  lines.push('})')
+  lines.push('')
+
+  return lines.join('\n')
+}
+
 function generateVariableFile(spec: ParsedSpec, vars: AddonVars): string {
   const { camelName, screamingName } = vars
   const displayName = vars.displayName.replace(/'/g, '')
@@ -1589,7 +1640,7 @@ function generateVariableFile(spec: ParsedSpec, vars: AddonVars): string {
 
   const lines: string[] = []
   lines.push("import { z } from 'zod'")
-  lines.push("import { wireVariable } from '@pikku/core/variable'")
+  lines.push("import { defineVariable } from '@pikku/core/variable'")
   lines.push('')
 
   const schemaVarName = `${camelName}BaseUrlSchema`
@@ -1606,7 +1657,7 @@ function generateVariableFile(spec: ParsedSpec, vars: AddonVars): string {
   }
 
   lines.push('')
-  lines.push(`wireVariable({`)
+  lines.push(`defineVariable({`)
   lines.push(`  name: '${screamingName}_BASE_URL',`)
   lines.push(`  displayName: '${displayName} Base URL',`)
   lines.push(`  description: 'The base URL for the ${displayName} API.',`)

package/src/naming.ts

@@ -3,18 +3,22 @@
  * Uses operationId when available, otherwise generates from path segments.
  */
 
-/** JavaScript/TypeScript reserved words that cannot be used as identifiers */
+/**
+ * Words that are illegal as a `const`/binding identifier in a strict-mode module
+ * (generated code is always ESM). Contextual keywords that are only special in a
+ * specific position — `get`/`set` (getters), `type`/`as`/`from`/`of` (type & import
+ * syntax), `any`/`number`/`object`/`string`/`symbol`/`declare`/`module`/`require`
+ * (type positions), and the legacy ES3 future-reserved words (`byte`, `char`, `int`,
+ * `long`, `short`, `float`, `double`, `boolean`, `goto`, `native`, `synchronized`,
+ * `transient`, `volatile`, `abstract`, `final`) — are all valid binding names and
+ * deliberately excluded, so `sheets.spreadsheets.get` stays `get`, not `_get`.
+ */
 const JS_RESERVED_WORDS = new Set([
-  // ECMAScript reserved words
-  'abstract',
   'arguments',
   'await',
-  'boolean',
   'break',
-  'byte',
   'case',
   'catch',
-  'char',
   'class',
   'const',
   'continue',
@@ -22,29 +26,22 @@ const JS_RESERVED_WORDS = new Set([
   'default',
   'delete',
   'do',
-  'double',
   'else',
   'enum',
   'eval',
   'export',
   'extends',
   'false',
-  'final',
   'finally',
-  'float',
   'for',
   'function',
-  'goto',
   'if',
   'implements',
   'import',
   'in',
   'instanceof',
-  'int',
   'interface',
   'let',
-  'long',
-  'native',
   'new',
   'null',
   'package',
@@ -52,40 +49,21 @@ const JS_RESERVED_WORDS = new Set([
   'protected',
   'public',
   'return',
-  'short',
   'static',
   'super',
   'switch',
-  'synchronized',
   'this',
   'throw',
   'throws',
-  'transient',
   'true',
   'try',
   'typeof',
   'undefined',
   'var',
   'void',
-  'volatile',
   'while',
   'with',
   'yield',
-  // TypeScript additional reserved words in strict mode
-  'as',
-  'any',
-  'declare',
-  'get',
-  'module',
-  'require',
-  'number',
-  'object',
-  'set',
-  'string',
-  'symbol',
-  'type',
-  'from',
-  'of',
 ])
 
 /**
@@ -234,6 +212,37 @@ interface OperationForNaming {
   operationId?: string
 }
 
+/**
+ * Find the longest shared leading run of dot-separated operationId segments,
+ * always leaving at least one trailing segment on every operation. Only applies
+ * when every operation has a dotted operationId (e.g. Google's
+ * `sheets.spreadsheets.values.get`), so specs whose ids are camelCase or absent
+ * are left untouched. The shared prefix is redundant with the addon namespace,
+ * so stripping it turns `sheetsSpreadsheetsValuesGet` into `valuesGet`.
+ */
+function commonOperationIdPrefix(operations: OperationForNaming[]): string[] {
+  if (operations.length < 2) {
+    return []
+  }
+  if (
+    !operations.every((op) => op.operationId && op.operationId.includes('.'))
+  ) {
+    return []
+  }
+  const segmented = operations.map((op) => op.operationId!.split('.'))
+  const minLen = Math.min(...segmented.map((s) => s.length))
+  const prefix: string[] = []
+  for (let i = 0; i < minLen - 1; i++) {
+    const seg = segmented[0][i]
+    if (segmented.every((s) => s[i] === seg)) {
+      prefix.push(seg)
+    } else {
+      break
+    }
+  }
+  return prefix
+}
+
 export interface NamedOperation {
   method: string
   path: string
@@ -257,11 +266,16 @@ export function generateOperationNames(
   // would produce files that collide on disk.
   const usedNamesLower = new Map<string, number>()
 
+  const opIdPrefix = commonOperationIdPrefix(operations)
+
   for (const op of operations) {
     let name: string
 
     if (op.operationId) {
-      name = fromOperationId(op.operationId)
+      const opId = opIdPrefix.length
+        ? op.operationId.split('.').slice(opIdPrefix.length).join('.')
+        : op.operationId
+      name = fromOperationId(opId)
     } else {
       name = deriveNameFromPath(op.method, op.path, commonPrefix)
     }