@workos/oagen-emitters 0.7.2 → 0.7.4

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-CGPujyaL.mjs";
+import { t as workosEmittersPlugin } from "./plugin-BoTAX4nl.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",
@@ -54,6 +54,6 @@
     "node": ">=24.10.0"
   },
   "dependencies": {
-    "@workos/oagen": "^0.12.0"
+    "@workos/oagen": "^0.15.0"
   }
 }

package/src/kotlin/path-expression.ts

@@ -0,0 +1,51 @@
+import { parsePathTemplate, hasPathParams } from '../shared/path-template.js';
+import { ktLiteral, propertyName } from './naming.js';
+
+/**
+ * The fully-qualified runtime helper that the generated code calls. Kotlin
+ * doesn't ship a path-segment URL encoder out of the box (java.net.URLEncoder
+ * is form-encoding — it encodes space as "+", which is wrong for path
+ * segments). The runtime helper lives in workos-kotlin at
+ * com.workos.common.http.encodePathSegment.
+ */
+export const KOTLIN_PATH_ENCODE_IMPORT = 'com.workos.common.http.encodePathSegment';
+
+export interface KotlinPathExpression {
+  /** The Kotlin expression to splice in as the `path = ...` argument. */
+  expression: string;
+  /** Whether the caller must add `KOTLIN_PATH_ENCODE_IMPORT` to its import set. */
+  requiresEncodeImport: boolean;
+}
+
+/**
+ * Build the Kotlin string-template that the SDK passes as the request path.
+ *
+ * Every {paramName} placeholder is wrapped in `encodePathSegment(...)` so a
+ * caller-supplied id containing "../" cannot be normalized by the underlying
+ * HTTP transport into a different endpoint of the WorkOS API while still
+ * authenticated with the application's API key.
+ *
+ *   "/orgs"            → `"orgs"`
+ *   "/orgs/{id}"       → `"orgs/${encodePathSegment(id)}"`
+ *   "/orgs/{id}/foo"   → `"orgs/${encodePathSegment(id)}/foo"`
+ */
+export function buildKotlinPathExpression(rawPath: string): KotlinPathExpression {
+  const segments = parsePathTemplate(rawPath);
+  if (!hasPathParams(segments)) {
+    return { expression: ktLiteral(rawPath), requiresEncodeImport: false };
+  }
+
+  let body = '';
+  for (const seg of segments) {
+    if (seg.kind === 'literal') {
+      body += escapeKotlinStringLiteral(seg.value);
+    } else {
+      body += `\${encodePathSegment(${propertyName(seg.name)})}`;
+    }
+  }
+  return { expression: `"${body}"`, requiresEncodeImport: true };
+}
+
+function escapeKotlinStringLiteral(literal: string): string {
+  return literal.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$');
+}

package/src/kotlin/resources.ts

@@ -37,6 +37,7 @@ import {
 import { generateWrapperMethods } from './wrappers.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { isHandwrittenOverride } from './overrides.js';
+import { buildKotlinPathExpression, KOTLIN_PATH_ENCODE_IMPORT } from './path-expression.js';
 
 const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
 
@@ -113,6 +114,11 @@ function generateApiClass(
       }
       // Wrapper methods use bodyOf() for request body construction.
       imports.add('com.workos.common.http.bodyOf');
+      // Wrappers share the operation's path; if it has any {param}, the
+      // wrapper emits encodePathSegment(...) and needs the import.
+      if (/\{[^{}]+\}/.test(resolvedOp!.operation.path)) {
+        imports.add(KOTLIN_PATH_ENCODE_IMPORT);
+      }
       const wrapperLines = generateWrapperMethods(resolvedOp!, ctx);
       if (body.length > 0) body.push('');
       for (const line of wrapperLines) body.push(line);
@@ -374,7 +380,9 @@ function renderMethod(
       (Object.keys(defaults).length > 0 || inferFromClient.length > 0) &&
       specDeclaresBody);
   const appendDefaultsAsQuery = !hasBody && (Object.keys(defaults).length > 0 || inferFromClient.length > 0);
-  const pathExpr = buildPathExpression(op.path, pathParams);
+  const pathBuilt = buildKotlinPathExpression(op.path);
+  const pathExpr = pathBuilt.expression;
+  if (pathBuilt.requiresEncodeImport) imports.add(KOTLIN_PATH_ENCODE_IMPORT);
 
   if (
     op.path === '/user_management/authenticate' &&
@@ -727,25 +735,6 @@ function _emitBodyField(field: Field, kotlinParamName: string, isPatch: boolean)
   return [`    if (${prop} != null) body[${ktLiteral(field.name)}] = ${prop}`];
 }
 
-function buildPathExpression(path: string, pathParams: Parameter[]): string {
-  if (pathParams.length === 0) return ktLiteral(path);
-  let result = path;
-  for (const pp of pathParams) {
-    const placeholder = `{${pp.name}}`;
-    const propName = propertyName(pp.name);
-    // Use $propName for simple identifiers and ${propName} only when followed by
-    // an ident-continuing char (to avoid false continuations). ktlint prefers the
-    // unbraced form for bare identifiers.
-    const replacement = isBareIdentifier(propName) ? `\$${propName}` : `\${${propName}}`;
-    result = result.replaceAll(placeholder, replacement);
-  }
-  return `"${result.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-}
-
-function isBareIdentifier(name: string): boolean {
-  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
-}
-
 function pickNamedQueryParam(sorted: Parameter[], name: string): string {
   const match = sorted.find((p) => p.name === name);
   return match ? propertyName(match.name) : 'null';

package/src/kotlin/wrappers.ts

@@ -1,8 +1,9 @@
-import type { EmitterContext, ResolvedOperation, ResolvedWrapper, Parameter } from '@workos/oagen';
+import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos/oagen';
 import { className, propertyName, ktLiteral, clientFieldExpression, escapeReserved } from './naming.js';
 import { mapTypeRef, mapTypeRefOptional } from './type-map.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { sortPathParamsByTemplateOrder } from './resources.js';
+import { buildKotlinPathExpression } from './path-expression.js';
 
 /**
  * Emit Kotlin wrapper methods for a union-split operation. Each wrapper
@@ -125,7 +126,7 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
     lines.push(`    val body = linkedMapOf<String, Any?>()`);
   }
 
-  const pathExpr = buildPathExpr(op.path, pathParams);
+  const pathExpr = buildKotlinPathExpression(op.path).expression;
   const httpMethod = op.httpMethod.toUpperCase();
 
   lines.push(`    val config =`);
@@ -154,15 +155,3 @@ function emitWrapperMethod(resolvedOp: ResolvedOperation, wrapper: ResolvedWrapp
 function escapeKdoc(s: string): string {
   return s.replace(/\*\//g, '*\u200b/');
 }
-
-function buildPathExpr(path: string, pathParams: Parameter[]): string {
-  if (pathParams.length === 0) return ktLiteral(path);
-  let result = path;
-  for (const pp of pathParams) {
-    const placeholder = `{${pp.name}}`;
-    const propName = propertyName(pp.name);
-    const replacement = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(propName) ? `\$${propName}` : `\${${propName}}`;
-    result = result.replaceAll(placeholder, replacement);
-  }
-  return `"${result.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-}

package/src/node/path-expression.ts

@@ -0,0 +1,37 @@
+import { parsePathTemplate, hasPathParams, type PathSegment } from '../shared/path-template.js';
+import { fieldName } from './naming.js';
+
+/**
+ * Build the TypeScript expression that the SDK passes as the request path.
+ *
+ * Every {paramName} placeholder becomes `${encodeURIComponent(name)}` inside a
+ * template literal. encodeURIComponent is used (not encodeURI) because we want
+ * "/" to be encoded too — otherwise a caller-supplied id containing "../" can
+ * be normalized by the underlying HTTP transport (libcurl, fetch, etc.) into
+ * a different endpoint of the WorkOS API while still authenticated with the
+ * application's API key.
+ *
+ *   "/orgs"            → `'orgs'`
+ *   "/orgs/{id}"       → `` `orgs/${encodeURIComponent(id)}` ``
+ *   "/orgs/{id}/foo"   → `` `orgs/${encodeURIComponent(id)}/foo` ``
+ */
+export function buildNodePathExpression(rawPath: string): string {
+  const segments = parsePathTemplate(rawPath);
+  if (!hasPathParams(segments)) {
+    return `'${rawPath}'`;
+  }
+
+  let body = '';
+  for (const seg of segments) {
+    body += renderSegment(seg);
+  }
+  return `\`${body}\``;
+}
+
+function renderSegment(seg: PathSegment): string {
+  if (seg.kind === 'literal') {
+    // Template-literal-safe escapes: backtick, backslash, ${
+    return seg.value.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+  }
+  return `\${encodeURIComponent(${fieldName(seg.name)})}`;
+}

package/src/node/resources.ts

@@ -40,6 +40,7 @@ import {
   getOpInferFromClient,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods, collectWrapperResponseModels } from './wrappers.js';
+import { buildNodePathExpression } from './path-expression.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 
 /**
@@ -1417,8 +1418,7 @@ function renderQueryExpr(queryParams: { name: string; required: boolean }[]): st
 }
 
 function buildPathStr(op: Operation): string {
-  const interpolated = op.path.replace(/\{(\w+)\}/g, (_, p) => `\${${fieldName(p)}}`);
-  return interpolated.includes('${') ? `\`${interpolated}\`` : `'${op.path}'`;
+  return buildNodePathExpression(op.path);
 }
 
 function buildPathParams(op: Operation, specEnumNames?: Set<string>): string {

package/src/node/wrappers.ts

@@ -3,6 +3,7 @@ import { toCamelCase } from '@workos/oagen';
 import { fieldName, resolveInterfaceName, wireInterfaceName } from './naming.js';
 import { mapTypeRef } from './type-map.js';
 import { resolveWrapperParams, formatWrapperDescription } from '../shared/wrapper-utils.js';
+import { buildNodePathExpression } from './path-expression.js';
 
 /**
  * Generate TypeScript wrapper method lines for union split operations.
@@ -157,8 +158,7 @@ function emitWrapperMethod(
 
 /** Build a path template string from an Operation. */
 function buildPathStr(op: { path: string; pathParams: Array<{ name: string }> }): string {
-  const interpolated = op.path.replace(/\{(\w+)\}/g, (_, p) => `\${${fieldName(p)}}`);
-  return interpolated.includes('${') ? `\`${interpolated}\`` : `'${op.path}'`;
+  return buildNodePathExpression(op.path);
 }
 
 /** Convert a JS value to a TypeScript literal. */

package/src/php/path-expression.ts

@@ -0,0 +1,52 @@
+import { parsePathTemplate, hasPathParams } from '../shared/path-template.js';
+import { fieldName } from './naming.js';
+
+export interface PhpPathOptions {
+  /**
+   * Raw OpenAPI param names whose runtime value is enum- or model-valued and
+   * therefore needs `->value` accessed before encoding. Mirrors the legacy
+   * resources.ts behavior that treated `kind === 'enum'` and `kind === 'model'`
+   * the same way.
+   */
+  valueAccessorParams?: ReadonlySet<string>;
+}
+
+/**
+ * Build the PHP expression that the SDK passes to HttpClient as `path:`.
+ *
+ * Concatenation, not interpolation: PHP does not allow function calls inside
+ * "..." strings, and every parameter must be wrapped in `rawurlencode(...)` so
+ * that an unencoded "../" in a caller-supplied id cannot be normalized by
+ * libcurl into a different endpoint of the WorkOS API while still
+ * authenticated with the application's API key.
+ *
+ *   "/orgs"            → `'orgs'`
+ *   "/orgs/{id}"       → `'orgs/' . rawurlencode($id)`
+ *   "/orgs/{id}/users" → `'orgs/' . rawurlencode($id) . '/users'`
+ *   "/orgs/{id}" with id ∈ valueAccessorParams → `'orgs/' . rawurlencode($id->value)`
+ */
+export function buildPhpPathExpression(rawPath: string, options: PhpPathOptions = {}): string {
+  const segments = parsePathTemplate(rawPath, { stripLeadingSlash: true });
+  if (segments.length === 0) return "''";
+
+  if (!hasPathParams(segments)) {
+    return phpSingleQuoted((segments[0] as { value: string }).value);
+  }
+
+  const valueAccessor = options.valueAccessorParams;
+  const parts: string[] = [];
+  for (const seg of segments) {
+    if (seg.kind === 'literal') {
+      parts.push(phpSingleQuoted(seg.value));
+    } else {
+      const varName = fieldName(seg.name);
+      const accessor = valueAccessor?.has(seg.name) ? `$${varName}->value` : `$${varName}`;
+      parts.push(`rawurlencode(${accessor})`);
+    }
+  }
+  return parts.join(' . ');
+}
+
+function phpSingleQuoted(literal: string): string {
+  return `'${literal.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}

package/src/php/resources.ts

@@ -14,6 +14,7 @@ import {
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods } from './wrappers.js';
 import { phpDocComment } from './utils.js';
+import { buildPhpPathExpression } from './path-expression.js';
 
 /**
  * Resolve the resource class name for a service (used by client.ts).
@@ -734,19 +735,11 @@ function buildBodyParamMap(op: Operation, bodyModel: Model | null): Map<string,
 }
 
 function buildPathString(op: Operation): string {
-  let path = op.path.startsWith('/') ? op.path.slice(1) : op.path;
-  if (op.pathParams.length === 0) {
-    return `'${path}'`;
-  }
-  // Build a map of param name → PHP expression (with ->value for enum types)
-  const paramExprs = new Map<string, string>();
+  const valueAccessor = new Set<string>();
   for (const p of op.pathParams) {
-    const phpName = fieldName(p.name);
-    const isEnum = p.type.kind === 'enum' || p.type.kind === 'model';
-    paramExprs.set(p.name, isEnum ? `{$${phpName}->value}` : `{$${phpName}}`);
+    if (p.type.kind === 'enum' || p.type.kind === 'model') valueAccessor.add(p.name);
   }
-  path = path.replace(/\{([^}]+)\}/g, (_match, param) => paramExprs.get(param) ?? `{$${fieldName(param)}}`);
-  return `"${path}"`;
+  return buildPhpPathExpression(op.path, { valueAccessorParams: valueAccessor });
 }
 
 function isEnumType(ref: import('@workos/oagen').TypeRef): boolean {

package/src/php/wrappers.ts

@@ -4,6 +4,7 @@ import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
 import { className, fieldName } from './naming.js';
 import { phpDocComment } from './utils.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
+import { buildPhpPathExpression } from './path-expression.js';
 
 /**
  * Generate PHP wrapper methods for split union operations.
@@ -108,15 +109,12 @@ function emitWrapperMethod(
 
   // Delegate to HTTP client
   const httpMethod = op.httpMethod.toUpperCase();
-  let path = op.path.startsWith('/') ? op.path.slice(1) : op.path;
-  const hasInterpolation = /\{[^}]+\}/.test(path);
-  path = path.replace(/\{([^}]+)\}/g, (_match, param) => `{$${fieldName(param)}}`);
-  const pathQuote = hasInterpolation ? '"' : "'";
+  const pathExpr = buildPhpPathExpression(op.path);
 
   lines.push('');
   lines.push('        $response = $this->client->request(');
   lines.push(`            method: '${httpMethod}',`);
-  lines.push(`            path: ${pathQuote}${path}${pathQuote},`);
+  lines.push(`            path: ${pathExpr},`);
   lines.push('            body: $body,');
   lines.push('            options: $options,');
   lines.push('        );');

package/src/python/path-expression.ts

@@ -0,0 +1,52 @@
+import { parsePathTemplate, hasPathParams } from '../shared/path-template.js';
+import { fieldName } from './naming.js';
+
+export interface PythonPathOptions {
+  /** Raw OpenAPI param names whose runtime value is enum-typed. */
+  enumParams?: ReadonlySet<string>;
+}
+
+/**
+ * Build the Python f-string that the SDK passes to the request layer.
+ *
+ * Every {paramName} placeholder is wrapped in
+ * `urllib.parse.quote(str(...), safe="")` so that an unencoded "/" or "../"
+ * in a caller-supplied id cannot be normalized by the underlying HTTP
+ * transport into a different endpoint of the WorkOS API while still
+ * authenticated with the application's API key. `safe=""` is critical:
+ * the stdlib default of `safe="/"` does NOT encode "/" and would leave the
+ * traversal vector open.
+ *
+ * Generated files using this helper must import `quote` (e.g.
+ * `from urllib.parse import quote`).
+ *
+ *   "/orgs"                        → `"orgs"`
+ *   "/orgs/{id}"                   → `f"orgs/{quote(str(id), safe='')}"`
+ *   "/orgs/{id}" with id ∈ enums   → `f"orgs/{quote(str(enum_value(id)), safe='')}"`
+ */
+export function buildPythonPathExpression(rawPath: string, options: PythonPathOptions = {}): string {
+  const segments = parsePathTemplate(rawPath, { stripLeadingSlash: true });
+  if (segments.length === 0) return '""';
+  if (!hasPathParams(segments)) {
+    const literal = (segments[0] as { value: string }).value;
+    return `"${escapePyDoubleQuoted(literal)}"`;
+  }
+
+  const enums = options.enumParams;
+  let body = '';
+  for (const seg of segments) {
+    if (seg.kind === 'literal') {
+      body += escapePyDoubleQuoted(seg.value);
+    } else {
+      const varName = fieldName(seg.name);
+      const inner = enums?.has(seg.name) ? `enum_value(${varName})` : varName;
+      body += `{quote(str(${inner}), safe='')}`;
+    }
+  }
+  return `f"${body}"`;
+}
+
+function escapePyDoubleQuoted(literal: string): string {
+  // f-strings: backslash, double-quote, and "{"/"}" all need escaping
+  return literal.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\{/g, '{{').replace(/\}/g, '}}');
+}

package/src/python/resources.ts

@@ -48,6 +48,7 @@ import {
   pythonLiteral,
   clientFieldExpression,
 } from './wrappers.js';
+import { buildPythonPathExpression } from './path-expression.js';
 
 /**
  * Compute the Python parameter name for a body field, prefixing with `body_` if it
@@ -1018,6 +1019,16 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
     lines.push('from __future__ import annotations');
     lines.push('');
     lines.push('from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Type, Union, cast');
+
+    // urllib.parse.quote is needed whenever any operation has a path parameter,
+    // so each interpolated id can be URL-encoded with safe="" before being
+    // concatenated into the request path.
+    const hasAnyPathParam =
+      allOperations.some((op) => op.pathParams.length > 0) || allOperations.some((op) => /\{[^{}]+\}/.test(op.path));
+    if (hasAnyPathParam) {
+      lines.push('from urllib.parse import quote');
+    }
+
     lines.push('');
     lines.push('if TYPE_CHECKING:');
     lines.push(`    from ${importPrefix}_client import AsyncWorkOSClient, WorkOSClient`);
@@ -1518,22 +1529,14 @@ function buildErrorRaisesBlock(op: Operation): string[] {
 
 /**
  * Build a Python f-string path expression from an operation path.
- * E.g., "/organizations/{id}" -> f"organizations/{id}"
+ * E.g., "/organizations/{id}" -> f"organizations/{quote(str(id), safe='')}"
  */
 function buildPathString(op: Operation): string {
-  // Strip leading slash and convert {param} to Python f-string interpolation
-  const path = op.path.replace(/^\//, '');
-  if (op.pathParams.length === 0) {
-    return `"${path}"`;
-  }
-  // Convert {paramName} to {fieldName(paramName)}
-  let fPath = path;
-  for (const param of op.pathParams) {
-    if (param.type.kind === 'enum' || (param.type.kind === 'nullable' && (param.type as any).inner?.kind === 'enum')) {
-      fPath = fPath.replace(`{${param.name}}`, `{enum_value(${fieldName(param.name)})}`);
-    } else {
-      fPath = fPath.replace(`{${param.name}}`, `{${fieldName(param.name)}}`);
+  const enumParams = new Set<string>();
+  for (const p of op.pathParams) {
+    if (p.type.kind === 'enum' || (p.type.kind === 'nullable' && (p.type as any).inner?.kind === 'enum')) {
+      enumParams.add(p.name);
     }
   }
-  return `f"${fPath}"`;
+  return buildPythonPathExpression(op.path, { enumParams });
 }

package/src/python/wrappers.ts

@@ -2,6 +2,7 @@ import type { EmitterContext, ResolvedOperation, ResolvedWrapper } from '@workos
 import { toSnakeCase } from '@workos/oagen';
 import { className, fieldName } from './naming.js';
 import { resolveWrapperParams, formatWrapperDescription } from '../shared/wrapper-utils.js';
+import { buildPythonPathExpression } from './path-expression.js';
 
 /**
  * Generate Python wrapper method lines for split operations.
@@ -115,16 +116,7 @@ function emitWrapperMethod(
   }
 
   // Build path expression
-  let pathExpr: string;
-  if (op.pathParams.length > 0) {
-    let path = op.path.replace(/^\//, '');
-    for (const p of op.pathParams) {
-      path = path.replace(`{${p.name}}`, `{${fieldName(p.name)}}`);
-    }
-    pathExpr = `f"${path}"`;
-  } else {
-    pathExpr = `"${op.path.replace(/^\//, '')}"`;
-  }
+  const pathExpr = buildPythonPathExpression(op.path);
 
   // Make the request
   const awaitPrefix = isAsync ? 'await ' : '';

package/src/shared/path-template.ts

@@ -0,0 +1,64 @@
+/**
+ * Helpers for parsing OpenAPI path templates into structured segments that
+ * each language emitter can render with proper per-segment URL encoding.
+ *
+ * SECURITY CONTEXT: every emitted path-parameter interpolation must wrap the
+ * runtime value in a URL-encoding call (e.g. `rawurlencode` in PHP,
+ * `encodeURIComponent` in TypeScript, `urllib.parse.quote(..., safe="")` in
+ * Python, a path-segment helper in Kotlin). Without per-segment encoding, a
+ * caller-supplied id containing "../" is silently normalized by libcurl
+ * (RFC 3986 dot-segment removal) before transmission, so the request reaches a
+ * different endpoint of the WorkOS API while still authenticated with the
+ * application's bearer token — i.e. forged cross-resource API requests under
+ * the application's API key. See workos-php HttpClient hardening for the
+ * defense-in-depth runtime guard; this module is the structural fix.
+ */
+
+export type PathSegment = { kind: 'literal'; value: string } | { kind: 'param'; name: string };
+
+export interface ParsePathOptions {
+  /** When true, drop a single leading "/" before parsing. */
+  stripLeadingSlash?: boolean;
+}
+
+/**
+ * Parse an OpenAPI path template into an ordered list of literal and
+ * parameter segments. Adjacent literals are coalesced into a single segment
+ * (the only way two literals can be adjacent is if the input had `{}{}`
+ * which is malformed; we still handle it deterministically).
+ *
+ * Examples:
+ *   "/orgs/{id}/users/{uid}" → [
+ *     { kind: 'literal', value: '/orgs/' },
+ *     { kind: 'param',   name:  'id' },
+ *     { kind: 'literal', value: '/users/' },
+ *     { kind: 'param',   name:  'uid' },
+ *   ]
+ *   "/health"               → [{ kind: 'literal', value: '/health' }]
+ *   ""                      → []
+ */
+export function parsePathTemplate(path: string, options: ParsePathOptions = {}): PathSegment[] {
+  const normalized = options.stripLeadingSlash && path.startsWith('/') ? path.slice(1) : path;
+  if (normalized === '') return [];
+
+  const segments: PathSegment[] = [];
+  const re = /\{([^{}]+)\}/g;
+  let cursor = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(normalized)) !== null) {
+    if (m.index > cursor) {
+      segments.push({ kind: 'literal', value: normalized.slice(cursor, m.index) });
+    }
+    segments.push({ kind: 'param', name: m[1] });
+    cursor = m.index + m[0].length;
+  }
+  if (cursor < normalized.length) {
+    segments.push({ kind: 'literal', value: normalized.slice(cursor) });
+  }
+  return segments;
+}
+
+/** True when at least one segment is a parameter placeholder. */
+export function hasPathParams(segments: PathSegment[]): boolean {
+  return segments.some((s) => s.kind === 'param');
+}

package/test/php/resources.test.ts

@@ -118,7 +118,7 @@ describe('generateResources', () => {
 
     expect(result[0].content).toContain('public function getOrganization(');
     expect(result[0].content).toContain('string $id');
-    expect(result[0].content).toContain('"organizations/{$id}"');
+    expect(result[0].content).toContain("'organizations/' . rawurlencode($id)");
     expect(result[0].content).toContain('Organization::fromArray($response)');
   });
 

package/test/python/resources.test.ts

@@ -83,7 +83,8 @@ describe('generateResources', () => {
     // GET method with path param
     expect(content).toContain('def get_organization(');
     expect(content).toContain('id: str,');
-    expect(content).toContain('f"organizations/{id}"');
+    expect(content).toContain(`f"organizations/{quote(str(id), safe='')}"`);
+    expect(content).toContain('from urllib.parse import quote');
     expect(content).toContain('model=Organization');
     // Public request methods (no underscore prefix)
     expect(content).toContain('self._client.request(');

package/test/shared/path-template.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { parsePathTemplate, hasPathParams } from '../../src/shared/path-template.js';
+
+describe('parsePathTemplate', () => {
+  it('splits a path with a single param', () => {
+    expect(parsePathTemplate('/orgs/{id}')).toEqual([
+      { kind: 'literal', value: '/orgs/' },
+      { kind: 'param', name: 'id' },
+    ]);
+  });
+
+  it('splits a path with multiple params', () => {
+    expect(parsePathTemplate('/orgs/{id}/users/{uid}')).toEqual([
+      { kind: 'literal', value: '/orgs/' },
+      { kind: 'param', name: 'id' },
+      { kind: 'literal', value: '/users/' },
+      { kind: 'param', name: 'uid' },
+    ]);
+  });
+
+  it('handles a path that ends in a param', () => {
+    expect(parsePathTemplate('/foo/{id}')).toEqual([
+      { kind: 'literal', value: '/foo/' },
+      { kind: 'param', name: 'id' },
+    ]);
+  });
+
+  it('handles a path that starts with a param', () => {
+    expect(parsePathTemplate('{id}/foo')).toEqual([
+      { kind: 'param', name: 'id' },
+      { kind: 'literal', value: '/foo' },
+    ]);
+  });
+
+  it('returns a single literal segment for paths with no params', () => {
+    expect(parsePathTemplate('/health')).toEqual([{ kind: 'literal', value: '/health' }]);
+  });
+
+  it('returns empty for an empty string', () => {
+    expect(parsePathTemplate('')).toEqual([]);
+  });
+
+  it('strips a single leading slash when requested', () => {
+    expect(parsePathTemplate('/orgs/{id}', { stripLeadingSlash: true })).toEqual([
+      { kind: 'literal', value: 'orgs/' },
+      { kind: 'param', name: 'id' },
+    ]);
+  });
+
+  it('preserves snake_case param names verbatim', () => {
+    expect(parsePathTemplate('/audit_logs/exports/{audit_log_export_id}')).toEqual([
+      { kind: 'literal', value: '/audit_logs/exports/' },
+      { kind: 'param', name: 'audit_log_export_id' },
+    ]);
+  });
+});
+
+describe('hasPathParams', () => {
+  it('returns true when any segment is a param', () => {
+    expect(hasPathParams(parsePathTemplate('/orgs/{id}'))).toBe(true);
+  });
+
+  it('returns false for paths with no params', () => {
+    expect(hasPathParams(parsePathTemplate('/health'))).toBe(false);
+  });
+
+  it('returns false for empty paths', () => {
+    expect(hasPathParams(parsePathTemplate(''))).toBe(false);
+  });
+});