@promobase/google-ads-sdk 0.1.1 → 0.1.2

package/src/clients/gaql/builder.ts

@@ -0,0 +1,120 @@
+import type { HttpClient } from "@promobase/sdk-runtime";
+import type { FieldInfo, FieldMap } from "../../generated/v23/gaql/field-map.ts";
+import type { GaqlResource, ResourceFieldMap } from "../../generated/v23/gaql/resource-map.ts";
+import { googleAdsService } from "../../generated/v23/services/index.ts";
+import { paginate } from "../../pagination.ts";
+import { type QueryState, serialize } from "./serialize.ts";
+
+type SplitDots<S extends string> = S extends `${infer H}.${infer T}` ? [H, ...SplitDots<T>] : [S];
+
+type SetPath<Root, Path extends readonly string[], V> = Path extends readonly [
+  infer Head extends string,
+  ...infer Rest extends string[],
+]
+  ? Rest extends readonly []
+    ? Root & { [K in Head]: V }
+    : Root & {
+        [K in Head]: SetPath<
+          Root extends Record<Head, infer Sub> ? Sub : Record<string, unknown>,
+          Rest,
+          V
+        >;
+      }
+  : Root;
+
+type ContributionOf<K extends string> = K extends keyof FieldMap
+  ? FieldMap[K] extends FieldInfo<infer NS, infer P, infer T>
+    ? SetPath<{}, [NS, ...SplitDots<P>], T>
+    : never
+  : never;
+
+type UnionToIntersection<U> = (U extends unknown ? (_: U) => void : never) extends (
+  _: infer I,
+) => void
+  ? I
+  : never;
+
+export type RowOf<Sel extends string> = UnionToIntersection<ContributionOf<Sel>>;
+
+export class QueryBuilder<FromR extends GaqlResource, Sel extends string = never> {
+  constructor(readonly state: QueryState<FromR, Sel>) {}
+
+  select<F extends Extract<ResourceFieldMap[FromR], string>>(
+    ...fields: readonly F[]
+  ): QueryBuilder<FromR, Sel | F> {
+    return new QueryBuilder<FromR, Sel | F>({
+      ...this.state,
+      select: [...this.state.select, ...fields] as readonly (Sel | F)[],
+    });
+  }
+
+  where(clause: string): QueryBuilder<FromR, Sel> {
+    return new QueryBuilder<FromR, Sel>({ ...this.state, where: clause });
+  }
+
+  orderBy(clause: string): QueryBuilder<FromR, Sel> {
+    return new QueryBuilder<FromR, Sel>({ ...this.state, orderBy: clause });
+  }
+
+  limit(n: number): QueryBuilder<FromR, Sel> {
+    return new QueryBuilder<FromR, Sel>({ ...this.state, limit: n });
+  }
+
+  parameters(clause: string): QueryBuilder<FromR, Sel> {
+    return new QueryBuilder<FromR, Sel>({ ...this.state, parameters: clause });
+  }
+
+  toQuery(): string {
+    return serialize(this.state);
+  }
+
+  async execute(
+    client: HttpClient,
+    customerId: string,
+  ): Promise<{ rows: RowOf<Sel>[]; nextPageToken?: string }> {
+    const res = await googleAdsService.search(client, customerId, {
+      query: this.toQuery(),
+    });
+    return {
+      rows: (res.results ?? []) as unknown as RowOf<Sel>[],
+      nextPageToken: res.nextPageToken,
+    };
+  }
+
+  stream(client: HttpClient, customerId: string): AsyncIterable<RowOf<Sel>> {
+    const query = this.toQuery();
+    return (async function* () {
+      for await (const row of paginate((req) => googleAdsService.search(client, customerId, req), {
+        query,
+      })) {
+        yield row as unknown as RowOf<Sel>;
+      }
+    })();
+  }
+
+  async toArray(client: HttpClient, customerId: string): Promise<RowOf<Sel>[]> {
+    const out: RowOf<Sel>[] = [];
+    for await (const row of this.stream(client, customerId)) out.push(row);
+    return out;
+  }
+
+  async take(n: number, client: HttpClient, customerId: string): Promise<RowOf<Sel>[]> {
+    const out: RowOf<Sel>[] = [];
+    for await (const row of this.stream(client, customerId)) {
+      out.push(row);
+      if (out.length >= n) break;
+    }
+    return out;
+  }
+
+  async first(client: HttpClient, customerId: string): Promise<RowOf<Sel> | null> {
+    for await (const row of this.stream(client, customerId)) return row;
+    return null;
+  }
+}
+
+export const gaql = {
+  from<R extends GaqlResource>(resource: R): QueryBuilder<R, never> {
+    return new QueryBuilder<R, never>({ from: resource, select: [] });
+  },
+};

package/src/clients/gaql/index.ts

@@ -0,0 +1,4 @@
+export { BoundQueryBuilder, gaqlFactory } from "./bound.ts";
+export type { RowOf } from "./builder.ts";
+export { gaql, QueryBuilder } from "./builder.ts";
+export type { QueryState } from "./serialize.ts";

package/src/clients/gaql/serialize.ts

@@ -0,0 +1,20 @@
+export interface QueryState<FromR extends string, Sel extends string> {
+  readonly from: FromR;
+  readonly select: readonly Sel[];
+  readonly where?: string;
+  readonly orderBy?: string;
+  readonly limit?: number;
+  readonly parameters?: string;
+}
+
+export function serialize<R extends string, S extends string>(state: QueryState<R, S>): string {
+  if (state.select.length === 0) {
+    throw new Error("gaql: select() must be called with at least one field");
+  }
+  const parts: string[] = [`SELECT ${state.select.join(", ")}`, `FROM ${state.from}`];
+  if (state.where) parts.push(`WHERE ${state.where}`);
+  if (state.orderBy) parts.push(`ORDER BY ${state.orderBy}`);
+  if (state.limit !== undefined) parts.push(`LIMIT ${state.limit}`);
+  if (state.parameters) parts.push(`PARAMETERS ${state.parameters}`);
+  return parts.join(" ");
+}

package/src/clients/index.ts

@@ -0,0 +1,15 @@
+export type { CreateAdGroupAdInput } from "./ad-group-ads.ts";
+export { adGroupAds } from "./ad-group-ads.ts";
+export type { CreateAdGroupInput } from "./ad-groups.ts";
+export { adGroups } from "./ad-groups.ts";
+export { ads } from "./ads.ts";
+export type { CreateCampaignBudgetInput } from "./campaign-budgets.ts";
+export { campaignBudgets } from "./campaign-budgets.ts";
+export type { CreateCampaignInput } from "./campaigns.ts";
+export { campaigns } from "./campaigns.ts";
+export type { Customer } from "./customer.ts";
+export { createCustomer } from "./customer.ts";
+export type { QueryState, RowOf } from "./gaql/index.ts";
+export { BoundQueryBuilder, gaql, gaqlFactory, QueryBuilder } from "./gaql/index.ts";
+export type { Ref } from "./types.ts";
+export { resolveRef } from "./types.ts";

package/src/clients/types.ts

@@ -0,0 +1,18 @@
+/**
+ * A reference to a Google Ads resource. Accepts either a raw `resourceName`
+ * string (e.g. `"customers/123/campaigns/456"`) or a rich resource object
+ * with a required `resourceName` field (typically the return value of a
+ * wrapper `create(...)` call).
+ *
+ * Note: because Google Ads resource interfaces have all-optional fields,
+ * TypeScript's structural typing treats `Ref<Campaign>` and
+ * `Ref<CampaignBudget>` as interchangeable at the type level. The wrappers
+ * rely on the CALL SITE (e.g. `adGroups.create({ campaign: ... })`) to keep
+ * the caller honest; a mistakenly passed budget-as-campaign will fail at
+ * runtime with a Google Ads API error, not at compile time.
+ */
+export type Ref<T extends { resourceName?: string }> = string | (T & { resourceName: string });
+
+export function resolveRef<T extends { resourceName?: string }>(ref: Ref<T>): string {
+  return typeof ref === "string" ? ref : ref.resourceName;
+}

package/src/codegen/emitter.ts

@@ -0,0 +1,119 @@
+import { parseHttpPath, snakeToCamel } from "./http-binding.ts";
+import type { EnumAst, FieldAst, MessageAst, MethodAst, ServiceAst } from "./parser.ts";
+import { resolveType } from "./type-resolver.ts";
+
+export function emitEnum(e: EnumAst, emittedName?: string): string {
+  const name = emittedName ?? e.name;
+  const values = e.values.map((v) => `  | "${v.name}"`).join("\n");
+  return `// Generated from ${e.fullName}. Do not edit by hand.\nexport type ${name} =\n${values};\n`;
+}
+
+export function emitMessage(
+  m: MessageAst,
+  shortNameMap?: Map<string, string>,
+  emittedName?: string,
+): string {
+  const selfName = emittedName ?? m.name;
+  const imports = new Set<string>();
+  const lines: string[] = [];
+  for (const f of m.fields) {
+    const resolved = resolveType(f.type, f.repeated, f.map ?? null, shortNameMap);
+    for (const imp of resolved.imports) {
+      if (imp.name !== selfName) imports.add(imp.name);
+    }
+    const jsName = snakeToCamel(f.name);
+    lines.push(`  ${jsName}?: ${resolved.tsType};`);
+  }
+  const importLine =
+    imports.size > 0
+      ? `import type { ${[...imports].sort().join(", ")} } from "../index.ts";\n\n`
+      : "";
+  return `${importLine}// Generated from ${m.fullName}. Do not edit by hand.\nexport interface ${selfName} {\n${lines.join("\n")}\n}\n`;
+}
+
+export function emitService(
+  s: ServiceAst,
+  messageIndex: Map<string, MessageAst>,
+  shortNameMap?: Map<string, string>,
+): string {
+  const methodBlocks: string[] = [];
+  const usedTypes = new Set<string>();
+
+  for (const m of s.methods) {
+    const block = emitMethod(m, messageIndex, usedTypes, shortNameMap);
+    if (block) methodBlocks.push(block);
+  }
+
+  const instance = s.name.charAt(0).toLowerCase() + s.name.slice(1);
+  const typeImports = [...usedTypes].sort();
+  const typeImportBlock =
+    typeImports.length > 0 ? `import type { ${typeImports.join(", ")} } from "../index.ts";\n` : "";
+
+  const body = methodBlocks.length > 0 ? `\n${methodBlocks.join(",\n\n")}\n` : "";
+
+  return `${typeImportBlock}import type { HttpClient } from "@promobase/sdk-runtime";\n\n// Generated from ${s.fullName}. Do not edit by hand.\nexport const ${instance} = {${body}};\n`;
+}
+
+function emitMethod(
+  m: MethodAst,
+  messageIndex: Map<string, MessageAst>,
+  usedTypes: Set<string>,
+  shortNameMap: Map<string, string> | undefined,
+): string | null {
+  if (!m.httpOption) return null;
+
+  const parsed = parseHttpPath(m.httpOption.path);
+  const methodName = m.name.charAt(0).toLowerCase() + m.name.slice(1);
+
+  // Use the type resolver to figure out what the request / response types
+  // should look like in TS. Well-known types (google.protobuf.Empty,
+  // google.longrunning.Operation, google.rpc.Status, …) resolve to scalar/
+  // `unknown` TS shapes with no import, which avoids dangling references
+  // to types that were never emitted.
+  const reqResolved = resolveType(m.requestType, false, null, shortNameMap);
+  const resResolved = resolveType(m.responseType, false, null, shortNameMap);
+  for (const imp of reqResolved.imports) usedTypes.add(imp.name);
+  for (const imp of resResolved.imports) usedTypes.add(imp.name);
+  const reqTs = reqResolved.tsType;
+  const resTs = resResolved.tsType;
+
+  const req = messageIndex.get(m.requestType);
+  const pathParamSet = new Set(parsed.pathParams);
+  const pathParamSignature = parsed.pathParams.map((p) => `${snakeToCamel(p)}: string`).join(", ");
+
+  const verb = m.httpOption.verb;
+  const needsBody = verb === "post" || verb === "put" || verb === "patch";
+
+  // Only try to `Omit<ReqShape, pathKeys>` when the resolved request type is
+  // a real generated interface we can index into. For well-known scalars we
+  // just use the resolved type directly.
+  const reqIsInterface = reqResolved.imports.length > 0;
+  const omitKeys =
+    reqIsInterface && parsed.pathParams.length > 0
+      ? parsed.pathParams.map((p) => `"${snakeToCamel(p)}"`).join(" | ")
+      : null;
+  const bodyFieldsTs = omitKeys ? `Omit<${reqTs}, ${omitKeys}>` : reqTs;
+
+  const nonPathFields: FieldAst[] = req ? req.fields.filter((f) => !pathParamSet.has(f.name)) : [];
+
+  const args: string[] = [`client: HttpClient`];
+  if (pathParamSignature) args.push(pathParamSignature);
+
+  let call: string;
+  if (needsBody) {
+    args.push(`body: ${bodyFieldsTs}`);
+    call = `client.post<${resTs}>(\`${parsed.template}\`, body)`;
+  } else if (verb === "delete") {
+    call = `client.delete<${resTs}>(\`${parsed.template}\`)`;
+  } else {
+    // GET
+    if (nonPathFields.length > 0) {
+      args.push(`query: ${bodyFieldsTs} = {} as ${bodyFieldsTs}`);
+      call = `client.get<${resTs}>(\`${parsed.template}\`, { query: query as Record<string, string | number | boolean | undefined> })`;
+    } else {
+      call = `client.get<${resTs}>(\`${parsed.template}\`)`;
+    }
+  }
+
+  return `  ${methodName}(${args.join(", ")}): Promise<${resTs}> {\n    return ${call};\n  }`;
+}

package/src/codegen/gaql-emitter.ts

@@ -0,0 +1,334 @@
+import { snakeToCamel } from "./http-binding.ts";
+import type { EnumAst, MessageAst, ProtoRoot } from "./parser.ts";
+import { resolveType } from "./type-resolver.ts";
+
+const SCALAR_TYPES = new Set([
+  "string",
+  "bool",
+  "bytes",
+  "double",
+  "float",
+  "int32",
+  "uint32",
+  "sint32",
+  "fixed32",
+  "sfixed32",
+  "int64",
+  "uint64",
+  "sint64",
+  "fixed64",
+  "sfixed64",
+]);
+
+export interface GaqlFieldEntry {
+  gaqlKey: string;
+  namespace: string;
+  camelPath: string;
+  tsType: string;
+  enumImport?: string;
+}
+
+export interface GaqlResourceCatalog {
+  resourceName: string;
+  typeAlias: string;
+  fields: GaqlFieldEntry[];
+}
+
+export interface GaqlCatalog {
+  resources: Map<string, GaqlResourceCatalog>;
+  metrics: GaqlFieldEntry[];
+  segments: GaqlFieldEntry[];
+  renderResourceFile(resource: string): string;
+  renderMetricsFile(): string;
+  renderSegmentsFile(): string;
+  renderFieldMapFile(): string;
+  renderResourceMapFile(): string;
+  renderIndexFile(): string;
+}
+
+export interface EmitterOptions {
+  resourcesPackagePrefix: string;
+  metricsMessageFullName: string | null;
+  segmentsMessageFullName: string | null;
+  /**
+   * Map of proto fullName -> canonical TS short name, matching the one used
+   * when emitting enums/messages to disk. Without this map the resolver
+   * falls back to the trailing `.` segment which is typically wrong when
+   * mangling collisions (e.g. `ProductChannel` vs `ProductChannelEnum`).
+   */
+  shortNameMap?: Map<string, string>;
+}
+
+const MAX_DEPTH = 6;
+
+export function emitGaqlCatalog(root: ProtoRoot, opts: EmitterOptions): GaqlCatalog {
+  const messageIndex = new Map<string, MessageAst>();
+  for (const m of root.messages) messageIndex.set(m.fullName, m);
+  const messageByShortName = new Map<string, MessageAst>();
+  for (const m of root.messages) {
+    if (!messageByShortName.has(m.name)) messageByShortName.set(m.name, m);
+  }
+  const enumByShortName = new Map<string, EnumAst>();
+  const enumByFullName = new Map<string, EnumAst>();
+  for (const e of root.enums) {
+    enumByFullName.set(e.fullName, e);
+    if (!enumByShortName.has(e.name)) enumByShortName.set(e.name, e);
+  }
+
+  // Set of TS names (as they appear on disk in ../enums/) that are actually
+  // enums. Uses the orchestrator's shortNameMap when provided so mangled
+  // names (ProductChannelEnum_ProductChannel) resolve correctly; otherwise
+  // falls back to each enum's proto short name.
+  const enumTsNames = new Set<string>();
+  for (const e of root.enums) {
+    const tsName = opts.shortNameMap?.get(e.fullName) ?? e.name;
+    enumTsNames.add(tsName);
+  }
+
+  const ctx: WalkContext = {
+    messageIndex,
+    messageByShortName,
+    enumByShortName,
+    enumByFullName,
+    enumTsNames,
+    shortNameMap: opts.shortNameMap,
+  };
+
+  const prefixSegments = opts.resourcesPackagePrefix.split(".").length;
+
+  // A top-level message under the resources package is treated as a GAQL
+  // resource iff it's the "primary" message for its source .proto file, i.e.
+  // its snake_case form matches the basename of the file it's defined in.
+  // This cleanly separates resources (e.g. `AdGroupAd` in `ad_group_ad.proto`)
+  // from sibling helper types defined in the same file (e.g.
+  // `AdGroupAdPolicySummary`). Falls back to the legacy "not referenced"
+  // heuristic when no sourceFile info is available (fixtures / in-memory).
+  const referencedTypes = new Set<string>();
+  for (const m of root.messages) {
+    for (const f of m.fields) {
+      if (!SCALAR_TYPES.has(f.type)) referencedTypes.add(f.type);
+    }
+  }
+
+  const resources = new Map<string, GaqlResourceCatalog>();
+  for (const m of root.messages) {
+    if (!m.fullName.startsWith(`${opts.resourcesPackagePrefix}.`)) continue;
+    if (m.fullName.split(".").length !== prefixSegments + 1) continue;
+    const snake = toSnakeCase(m.name);
+    if (m.sourceFile) {
+      const stem = m.sourceFile
+        .replace(/\\/g, "/")
+        .split("/")
+        .pop()!
+        .replace(/\.proto$/, "");
+      if (stem !== snake) continue;
+    } else {
+      if (referencedTypes.has(m.name) || referencedTypes.has(m.fullName)) continue;
+    }
+    const resourceName = snake;
+    const typeAlias = `${m.name}SelectableField`;
+    const fields: GaqlFieldEntry[] = [];
+    walkMessage(m, [resourceName], [], fields, ctx, 0);
+    resources.set(resourceName, { resourceName, typeAlias, fields });
+  }
+
+  const metrics: GaqlFieldEntry[] = [];
+  if (opts.metricsMessageFullName) {
+    const metricsMsg = messageIndex.get(opts.metricsMessageFullName);
+    if (metricsMsg) walkMessage(metricsMsg, ["metrics"], [], metrics, ctx, 0);
+  }
+
+  const segments: GaqlFieldEntry[] = [];
+  if (opts.segmentsMessageFullName) {
+    const segmentsMsg = messageIndex.get(opts.segmentsMessageFullName);
+    if (segmentsMsg) walkMessage(segmentsMsg, ["segments"], [], segments, ctx, 0);
+  }
+
+  return {
+    resources,
+    metrics,
+    segments,
+    renderResourceFile(resource) {
+      const cat = resources.get(resource);
+      if (!cat) throw new Error(`unknown resource: ${resource}`);
+      const lines = cat.fields.map((f) => `  | "${f.gaqlKey}"`);
+      return `// Generated. Do not edit by hand.\nexport type ${cat.typeAlias} =\n${lines.join("\n") || "  never"};\n`;
+    },
+    renderMetricsFile() {
+      const lines = metrics.map((f) => `  | "${f.gaqlKey}"`);
+      return `// Generated. Do not edit by hand.\nexport type MetricField =\n${lines.join("\n") || "  never"};\n`;
+    },
+    renderSegmentsFile() {
+      const lines = segments.map((f) => `  | "${f.gaqlKey}"`);
+      return `// Generated. Do not edit by hand.\nexport type SegmentField =\n${lines.join("\n") || "  never"};\n`;
+    },
+    renderFieldMapFile() {
+      const all = [...[...resources.values()].flatMap((r) => r.fields), ...metrics, ...segments];
+      const enumImports = new Set<string>();
+      for (const f of all) if (f.enumImport) enumImports.add(f.enumImport);
+      const importLines = [...enumImports]
+        .sort()
+        .map((name) => `import type { ${name} } from "../enums/${name}.ts";`)
+        .join("\n");
+      // Any non-enum message type referenced from field-map.ts isn't imported
+      // (we only import enums). Downgrade those to `unknown` so the file
+      // remains self-contained and typecheck-clean. Scalar primitives and
+      // Record<> types pass through, as do known enum types.
+      const SAFE = new Set(["string", "number", "boolean", "unknown"]);
+      const sanitize = (tsType: string, enumImport?: string): string => {
+        const isArray = tsType.endsWith("[]");
+        const base = tsType.replace(/\[\]$/, "");
+        if (enumImport && base === enumImport) return tsType;
+        if (SAFE.has(base)) return tsType;
+        if (base.startsWith("Record<")) return tsType;
+        return isArray ? "unknown[]" : "unknown";
+      };
+      const entries = all
+        .map((f) => {
+          const ts = sanitize(f.tsType, f.enumImport);
+          return `  "${f.gaqlKey}": FieldInfo<"${f.namespace}", "${f.camelPath}", ${ts}>;`;
+        })
+        .join("\n");
+      return `${importLines}\n\n// Generated. Do not edit by hand.\nexport interface FieldInfo<NS extends string, P extends string, T> {\n  namespace: NS;\n  path: P;\n  tsType: T;\n}\n\nexport type FieldMap = {\n${entries}\n};\n`;
+    },
+    renderResourceMapFile() {
+      const resImports = [...resources.values()]
+        .map((r) => `import type { ${r.typeAlias} } from "./resources/${r.resourceName}.ts";`)
+        .join("\n");
+      const entries = [...resources.values()]
+        .map((r) => `  ${r.resourceName}: ${r.typeAlias} | MetricField | SegmentField;`)
+        .join("\n");
+      return `${resImports}\nimport type { MetricField } from "./metrics.ts";\nimport type { SegmentField } from "./segments.ts";\n\n// Generated. Do not edit by hand.\nexport type ResourceFieldMap = {\n${entries}\n};\n\nexport type GaqlResource = keyof ResourceFieldMap;\n`;
+    },
+    renderIndexFile() {
+      const lines = [
+        `export * from "./field-map.ts";`,
+        `export * from "./resource-map.ts";`,
+        `export * from "./metrics.ts";`,
+        `export * from "./segments.ts";`,
+      ];
+      for (const r of resources.values()) {
+        lines.push(`export * from "./resources/${r.resourceName}.ts";`);
+      }
+      return `${lines.join("\n")}\n`;
+    },
+  };
+}
+
+interface WalkContext {
+  messageIndex: Map<string, MessageAst>;
+  messageByShortName: Map<string, MessageAst>;
+  enumByShortName: Map<string, EnumAst>;
+  enumByFullName: Map<string, EnumAst>;
+  enumTsNames: Set<string>;
+  shortNameMap?: Map<string, string>;
+}
+
+function lookupMessage(protoType: string, ctx: WalkContext): MessageAst | undefined {
+  const normalized = protoType.replace(/^\./, "");
+  return ctx.messageIndex.get(normalized) ?? ctx.messageByShortName.get(normalized);
+}
+
+function lookupEnum(protoType: string, ctx: WalkContext): EnumAst | undefined {
+  const normalized = protoType.replace(/^\./, "");
+  return ctx.enumByFullName.get(normalized) ?? ctx.enumByShortName.get(normalized);
+}
+
+function walkMessage(
+  msg: MessageAst,
+  namespacePath: string[],
+  camelPath: string[],
+  out: GaqlFieldEntry[],
+  ctx: WalkContext,
+  depth: number,
+) {
+  if (depth > MAX_DEPTH) return;
+  for (const field of msg.fields) {
+    if (field.map) continue;
+
+    const snakeLeaf = field.name;
+    const camelLeaf = snakeToCamel(field.name);
+    const gaqlKey = [...namespacePath, snakeLeaf].join(".");
+    const namespace = namespacePath[0]!;
+    const fullCamelPath = [...camelPath, camelLeaf].join(".");
+
+    const resolved = resolveType(field.type, field.repeated, null, ctx.shortNameMap);
+    const isScalar = SCALAR_TYPES.has(field.type);
+    const wellKnown = isWellKnown(field.type);
+    const enumRef = !isScalar && !wellKnown ? lookupEnum(field.type, ctx) : undefined;
+
+    const pushLeaf = () => {
+      out.push({
+        gaqlKey,
+        namespace,
+        camelPath: fullCamelPath,
+        tsType: resolved.tsType,
+        enumImport: pickEnumImport(resolved, ctx),
+      });
+    };
+
+    if (isScalar || wellKnown || enumRef) {
+      pushLeaf();
+      continue;
+    }
+
+    if (field.repeated) {
+      pushLeaf();
+      continue;
+    }
+
+    const nested = lookupMessage(field.type, ctx);
+    if (!nested) {
+      pushLeaf();
+      continue;
+    }
+    walkMessage(
+      nested,
+      [...namespacePath, snakeLeaf],
+      [...camelPath, camelLeaf],
+      out,
+      ctx,
+      depth + 1,
+    );
+  }
+}
+
+function isWellKnown(protoType: string): boolean {
+  const t = protoType.replace(/^\./, "");
+  return (
+    t.startsWith("google.protobuf.") &&
+    (t.endsWith("Value") ||
+      t === "google.protobuf.Timestamp" ||
+      t === "google.protobuf.Duration" ||
+      t === "google.protobuf.FieldMask" ||
+      t === "google.protobuf.Empty" ||
+      t === "google.protobuf.Any" ||
+      t === "google.protobuf.Struct")
+  );
+}
+
+function pickEnumImport(
+  resolved: {
+    tsType: string;
+    imports: { name: string }[];
+  },
+  ctx: WalkContext,
+): string | undefined {
+  const base = resolved.tsType.replace(/\[\]$/, "");
+  if (["string", "number", "boolean", "unknown"].includes(base)) return undefined;
+  if (base.startsWith("Record<")) return undefined;
+  const found = resolved.imports.find((i) => i.name === base)?.name;
+  if (!found) return undefined;
+  // Only include as an enum import if we actually know it to be an enum — the
+  // emitter only writes enum files to `../enums/` so message imports here
+  // would dangle.
+  if (!ctx.enumTsNames.has(found)) return undefined;
+  return found;
+}
+
+function toSnakeCase(s: string): string {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase();
+}

package/src/codegen/http-binding.ts

@@ -0,0 +1,17 @@
+export interface ParsedHttpPath {
+  template: string;
+  pathParams: string[];
+}
+
+export function parseHttpPath(path: string): ParsedHttpPath {
+  const pathParams: string[] = [];
+  const template = path.replace(/\{([a-z_][a-z_0-9]*)(?:=[^}]*)?\}/g, (_match, name: string) => {
+    pathParams.push(name);
+    return `\${${snakeToCamel(name)}}`;
+  });
+  return { template, pathParams };
+}
+
+export function snakeToCamel(s: string): string {
+  return s.replace(/_([a-z])/g, (_m, c: string) => c.toUpperCase());
+}