@distilled.cloud/core 0.0.0 → 0.2.0

package/lib/retry.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Retry Policy System
+ *
+ * Provides configurable retry policies for API operations.
+ * Each SDK creates its own Retry service tag but uses these shared utilities
+ * for building retry schedules and policies.
+ *
+ * @example
+ * ```ts
+ * import * as Retry from "@distilled.cloud/sdk-core/retry";
+ *
+ * // Use the default retry policy
+ * myEffect.pipe(Retry.policy(myRetryService, Retry.makeDefault()))
+ *
+ * // Disable retries
+ * myEffect.pipe(Retry.none(myRetryService))
+ * ```
+ */
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as ServiceMap from "effect/ServiceMap";
+/**
+ * Retry policy options that match the Effect.retry contract.
+ */
+export interface Options {
+    /**
+     * Predicate to determine if an error should trigger a retry.
+     */
+    readonly while?: (error: unknown) => boolean;
+    /**
+     * The schedule to use for retrying.
+     */
+    readonly schedule?: Schedule.Schedule<unknown>;
+}
+/**
+ * A factory function that creates retry policy options with access to the last error ref.
+ * This allows dynamic policies that can inspect the last error for retry-after headers, etc.
+ */
+export type Factory = (lastError: Ref.Ref<unknown>) => Options;
+/**
+ * A retry policy can be either static options or a factory that receives the last error ref.
+ */
+export type Policy = Options | Factory;
+/**
+ * Create a typed Retry service class for an SDK.
+ * Each SDK should create its own Retry service using this factory.
+ *
+ * @example
+ * ```ts
+ * // In planetscale-sdk/src/retry.ts
+ * export class Retry extends makeRetryService("PlanetScaleRetry") {}
+ * ```
+ */
+export declare const makeRetryService: (name: string) => ServiceMap.ServiceClass<any, string, Policy>;
+/**
+ * Provides a custom retry policy for API calls.
+ */
+export declare const policy: (Service: any, optionsOrFactory: Policy) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, unknown, unknown>;
+/**
+ * Disables all automatic retries.
+ */
+export declare const none: (Service: any) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, unknown, unknown>;
+/**
+ * Custom jittered schedule helper.
+ * Adds random jitter between 0-50ms to avoid thundering herd.
+ */
+export declare const jittered: <Input, Error, Env>(self: Schedule.Schedule<unknown, Input, Error, Env>) => Schedule.Schedule<unknown, Input, Error, Env>;
+/**
+ * Cap delay at a maximum duration.
+ */
+export declare const capped: (max: Duration.Duration) => <Input, Error, Env>(self: Schedule.Schedule<Duration.Duration, Input, Error, Env>) => Schedule.Schedule<Duration.Duration, Input, Error, Env>;
+/**
+ * Creates the default retry policy.
+ *
+ * This policy:
+ * - Retries transient errors (throttling, server, network, locked errors)
+ * - Uses exponential backoff starting at 100ms with a factor of 2
+ * - Ensures at least 500ms delay for throttling errors
+ * - Limits to 5 retry attempts
+ * - Applies jitter to avoid thundering herd
+ */
+export declare const makeDefault: Factory;
+/**
+ * Retry options that retries all throttling errors indefinitely.
+ */
+export declare const throttlingOptions: Options;
+/**
+ * Retry options that retries all transient errors indefinitely.
+ *
+ * This includes:
+ * 1. Throttling errors
+ * 2. Server errors
+ * 3. Network errors
+ * 4. Locked errors (423)
+ */
+export declare const transientOptions: Options;
+//# sourceMappingURL=retry.d.ts.map

package/lib/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,GAAG,MAAM,YAAY,CAAC;AAClC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAOhD;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7C;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAMvC;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,gEACY,CAAC;AAE1C;;GAEG;AACH,eAAO,MAAM,MAAM,+CAEhB,CAAC,EAAE,CAAC,EAAE,CAAC,uEACiE,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,IAAI,qBAEd,CAAC,EAAE,CAAC,EAAE,CAAC,uEAIL,CAAC;AAMN;;;GAGG;AACH,eAAO,MAAM,QAAQ,2HAEpB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,MAAM,2KAKhB,CAAC;AAMJ;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,EAAE,OAkBxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAO/B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAO9B,CAAC"}

package/lib/retry.js

@@ -0,0 +1,106 @@
+/**
+ * Retry Policy System
+ *
+ * Provides configurable retry policies for API operations.
+ * Each SDK creates its own Retry service tag but uses these shared utilities
+ * for building retry schedules and policies.
+ *
+ * @example
+ * ```ts
+ * import * as Retry from "@distilled.cloud/sdk-core/retry";
+ *
+ * // Use the default retry policy
+ * myEffect.pipe(Retry.policy(myRetryService, Retry.makeDefault()))
+ *
+ * // Disable retries
+ * myEffect.pipe(Retry.none(myRetryService))
+ * ```
+ */
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { pipe } from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as ServiceMap from "effect/ServiceMap";
+import { isThrottling, isTransientError } from "./category.js";
+// ============================================================================
+// Retry Service Factory
+// ============================================================================
+/**
+ * Create a typed Retry service class for an SDK.
+ * Each SDK should create its own Retry service using this factory.
+ *
+ * @example
+ * ```ts
+ * // In planetscale-sdk/src/retry.ts
+ * export class Retry extends makeRetryService("PlanetScaleRetry") {}
+ * ```
+ */
+export const makeRetryService = (name) => ServiceMap.Service()(name);
+/**
+ * Provides a custom retry policy for API calls.
+ */
+export const policy = (Service, optionsOrFactory) => (effect) => Effect.provide(effect, Layer.succeed(Service, optionsOrFactory));
+/**
+ * Disables all automatic retries.
+ */
+export const none = (Service) => (effect) => Effect.provide(effect, Layer.succeed(Service, { while: () => false }));
+// ============================================================================
+// Retry Schedule Utilities
+// ============================================================================
+/**
+ * Custom jittered schedule helper.
+ * Adds random jitter between 0-50ms to avoid thundering herd.
+ */
+export const jittered = Schedule.addDelay(() => Effect.succeed(Duration.millis(Math.random() * 50)));
+/**
+ * Cap delay at a maximum duration.
+ */
+export const capped = (max) => Schedule.modifyDelay((duration) => Effect.succeed(Duration.isGreaterThan(duration, max) ? Duration.millis(5000) : duration));
+// ============================================================================
+// Default Retry Policies
+// ============================================================================
+/**
+ * Creates the default retry policy.
+ *
+ * This policy:
+ * - Retries transient errors (throttling, server, network, locked errors)
+ * - Uses exponential backoff starting at 100ms with a factor of 2
+ * - Ensures at least 500ms delay for throttling errors
+ * - Limits to 5 retry attempts
+ * - Applies jitter to avoid thundering herd
+ */
+export const makeDefault = (lastError) => ({
+    while: (error) => isTransientError(error),
+    schedule: pipe(Schedule.exponential(100, 2), Schedule.modifyDelay(Effect.fnUntraced(function* (duration) {
+        const error = yield* Ref.get(lastError);
+        if (isThrottling(error)) {
+            if (Duration.toMillis(duration) < 500) {
+                return Duration.toMillis(Duration.millis(500));
+            }
+        }
+        return Duration.toMillis(duration);
+    })), Schedule.both(Schedule.recurs(5)), jittered),
+});
+/**
+ * Retry options that retries all throttling errors indefinitely.
+ */
+export const throttlingOptions = {
+    while: (error) => isThrottling(error),
+    schedule: pipe(Schedule.exponential(1000, 2), capped(Duration.seconds(5)), jittered),
+};
+/**
+ * Retry options that retries all transient errors indefinitely.
+ *
+ * This includes:
+ * 1. Throttling errors
+ * 2. Server errors
+ * 3. Network errors
+ * 4. Locked errors (423)
+ */
+export const transientOptions = {
+    while: isTransientError,
+    schedule: pipe(Schedule.exponential(1000, 2), capped(Duration.seconds(5)), jittered),
+};
+//# sourceMappingURL=retry.js.map

package/lib/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/lib/sensitive.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Sensitive data schemas for handling credentials and secrets.
+ *
+ * This module provides schemas that wrap sensitive data in Effect's Redacted type,
+ * preventing accidental logging of secrets like passwords and tokens.
+ *
+ * @example
+ * ```ts
+ * import { SensitiveString } from "@distilled.cloud/sdk-core/sensitive";
+ *
+ * const Password = Schema.Struct({ plain_text: SensitiveString });
+ *
+ * // Users can pass raw strings (convenient):
+ * API.createPassword({ plain_text: "my-secret" })
+ *
+ * // Or Redacted values (explicit):
+ * API.createPassword({ plain_text: Redacted.make("my-secret") })
+ *
+ * // Response values are always Redacted (safe):
+ * console.log(result.plain_text); // logs "<redacted>"
+ * ```
+ */
+import * as Redacted from "effect/Redacted";
+import * as S from "effect/Schema";
+/**
+ * Sensitive - Marks data as sensitive, wrapping in Effect's Redacted type.
+ *
+ * This schema provides a convenient way to handle sensitive data:
+ * - TypeScript type: `A | Redacted.Redacted<A>` (accepts both for inputs)
+ * - Decode (responses): Always wraps wire value in Redacted
+ * - Encode (requests): Accepts BOTH raw values and Redacted, extracts the raw value
+ *
+ * The union type allows users to conveniently pass plain values for inputs while
+ * still getting proper Redacted types for outputs. Response values will always
+ * be Redacted, which prevents accidental logging.
+ */
+export declare const Sensitive: <A>(schema: S.Schema<A>) => S.Schema<A | Redacted.Redacted<A>>;
+/**
+ * Sensitive string - a string marked as sensitive.
+ * Wire format is plain string, TypeScript type is string | Redacted<string>.
+ * At runtime, decoded values are always Redacted<string>.
+ */
+export declare const SensitiveString: S.Schema<string | Redacted.Redacted<string>>;
+/**
+ * Sensitive nullable string - a nullable string marked as sensitive.
+ * Wire format is plain string | null, TypeScript type is string | null | Redacted<string>.
+ * At runtime, decoded non-null values are always Redacted<string>.
+ */
+export declare const SensitiveNullableString: S.NullOr<S.Schema<string | Redacted.Redacted<string>>>;
+//# sourceMappingURL=sensitive.d.ts.map

package/lib/sensitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive.d.ts","sourceRoot":"","sources":["../src/sensitive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,CAAC,MAAM,eAAe,CAAC;AAGnC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,4DAiBrB,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,eAAe,8CAE1B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,wDAElC,CAAC"}

package/lib/sensitive.js

@@ -0,0 +1,64 @@
+/**
+ * Sensitive data schemas for handling credentials and secrets.
+ *
+ * This module provides schemas that wrap sensitive data in Effect's Redacted type,
+ * preventing accidental logging of secrets like passwords and tokens.
+ *
+ * @example
+ * ```ts
+ * import { SensitiveString } from "@distilled.cloud/sdk-core/sensitive";
+ *
+ * const Password = Schema.Struct({ plain_text: SensitiveString });
+ *
+ * // Users can pass raw strings (convenient):
+ * API.createPassword({ plain_text: "my-secret" })
+ *
+ * // Or Redacted values (explicit):
+ * API.createPassword({ plain_text: Redacted.make("my-secret") })
+ *
+ * // Response values are always Redacted (safe):
+ * console.log(result.plain_text); // logs "<redacted>"
+ * ```
+ */
+import * as Redacted from "effect/Redacted";
+import * as S from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+/**
+ * Sensitive - Marks data as sensitive, wrapping in Effect's Redacted type.
+ *
+ * This schema provides a convenient way to handle sensitive data:
+ * - TypeScript type: `A | Redacted.Redacted<A>` (accepts both for inputs)
+ * - Decode (responses): Always wraps wire value in Redacted
+ * - Encode (requests): Accepts BOTH raw values and Redacted, extracts the raw value
+ *
+ * The union type allows users to conveniently pass plain values for inputs while
+ * still getting proper Redacted types for outputs. Response values will always
+ * be Redacted, which prevents accidental logging.
+ */
+export const Sensitive = (schema) => schema
+    .pipe(S.decodeTo(S.Union([S.toType(schema), S.Redacted(S.toType(schema))]), SchemaTransformation.transform({
+    // Decode: wire format -> always wrap in Redacted
+    decode: (a) => Redacted.make(a),
+    // Encode: accept both raw and Redacted -> extract raw value
+    encode: (v) => (Redacted.isRedacted(v) ? Redacted.value(v) : v),
+})))
+    .annotate({
+    identifier: `Sensitive<${schema.ast.annotations?.identifier ?? "unknown"}>`,
+});
+/**
+ * Sensitive string - a string marked as sensitive.
+ * Wire format is plain string, TypeScript type is string | Redacted<string>.
+ * At runtime, decoded values are always Redacted<string>.
+ */
+export const SensitiveString = Sensitive(S.String).annotate({
+    identifier: "SensitiveString",
+});
+/**
+ * Sensitive nullable string - a nullable string marked as sensitive.
+ * Wire format is plain string | null, TypeScript type is string | null | Redacted<string>.
+ * At runtime, decoded non-null values are always Redacted<string>.
+ */
+export const SensitiveNullableString = S.NullOr(SensitiveString).annotate({
+    identifier: "SensitiveNullableString",
+});
+//# sourceMappingURL=sensitive.js.map

package/lib/sensitive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive.js","sourceRoot":"","sources":["../src/sensitive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,CAAC,MAAM,eAAe,CAAC;AACnC,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,MAAmB,EACiB,EAAE,CACtC,MAAM;KACH,IAAI,CACH,CAAC,CAAC,QAAQ,CACR,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EACzD,oBAAoB,CAAC,SAAS,CAAC;IAC7B,iDAAiD;IACjD,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAQ;IACtC,4DAA4D;IAC5D,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE,CAAC,CACH,CACF;KACA,QAAQ,CAAC;IACR,UAAU,EAAE,aAAa,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,UAAU,IAAI,SAAS,GAAG;CAC5E,CAAC,CAAC;AAEP;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC;IAC1D,UAAU,EAAE,iBAAiB;CAC9B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC;IACxE,UAAU,EAAE,yBAAyB;CACtC,CAAC,CAAC"}

package/lib/traits.d.ts

@@ -0,0 +1,265 @@
+import * as AST from "effect/SchemaAST";
+/**
+ * Internal symbol for annotation metadata storage.
+ */
+declare const annotationMetaSymbol: unique symbol;
+/**
+ * Any type that has an .annotate() method returning itself.
+ * This includes Schema.Schema and Schema.PropertySignature.
+ */
+type Annotatable = {
+    annotate(annotations: unknown): Annotatable;
+};
+/**
+ * An Annotation is a callable that can be used with .pipe() AND
+ * has symbol properties so it works directly with Schema.Struct/Class.
+ *
+ * The index signatures allow TypeScript to accept this as a valid annotations object.
+ */
+export interface Annotation {
+    <A extends Annotatable>(schema: A): A;
+    readonly [annotationMetaSymbol]: Array<{
+        symbol: symbol;
+        value: unknown;
+    }>;
+    readonly [key: symbol]: unknown;
+    readonly [key: string]: unknown;
+}
+/**
+ * Create an annotation builder for a given symbol and value.
+ * This is the core primitive used to build all trait annotations.
+ */
+export declare function makeAnnotation<T>(sym: symbol, value: T): Annotation;
+/**
+ * Combine multiple annotations into one.
+ * Use when you need multiple annotations on the same schema.
+ *
+ * @example
+ * ```ts
+ * const MyInput = Schema.Struct({
+ *   id: Schema.String.pipe(T.all(T.PathParam(), T.Required())),
+ * });
+ * ```
+ */
+export declare function all(...annotations: Annotation[]): Annotation;
+/** Symbol for HTTP operation metadata (method + path template) */
+export declare const httpSymbol: unique symbol;
+/** HTTP method type */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+/** HTTP trait configuration */
+export interface HttpTrait {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Path template with {param} placeholders */
+    path: string;
+    /** Content type override (e.g., "multipart") */
+    contentType?: string;
+    /** Whether the request has a body (used by GCP generator) */
+    hasBody?: boolean;
+}
+/**
+ * Http trait - defines the HTTP method and path template for an operation.
+ * Path parameters are specified using {paramName} syntax.
+ *
+ * @example
+ * ```ts
+ * const GetDatabaseInput = Schema.Struct({
+ *   organization: Schema.String.pipe(T.PathParam()),
+ *   database: Schema.String.pipe(T.PathParam()),
+ * }).pipe(
+ *   T.Http({ method: "GET", path: "/organizations/{organization}/databases/{database}" })
+ * );
+ * ```
+ */
+export declare const Http: (trait: HttpTrait) => Annotation;
+/** Symbol for path parameter annotation */
+export declare const pathParamSymbol: unique symbol;
+/**
+ * PathParam trait - marks a field as a path parameter.
+ * The field name is used as the placeholder name in the path template.
+ *
+ * @example
+ * ```ts
+ * const Input = Schema.Struct({
+ *   organization: Schema.String.pipe(T.PathParam()),
+ * }).pipe(
+ *   T.Http({ method: "GET", path: "/organizations/{organization}" })
+ * );
+ * ```
+ */
+export declare const PathParam: () => Annotation;
+/** Symbol for query parameter annotation */
+export declare const queryParamSymbol: unique symbol;
+/**
+ * QueryParam trait - marks a field as a query parameter.
+ * Optionally specify a different wire name.
+ *
+ * @example
+ * ```ts
+ * const Input = Schema.Struct({
+ *   perPage: Schema.optional(Schema.Number).pipe(T.QueryParam("per_page")),
+ * });
+ * ```
+ */
+export declare const QueryParam: (name?: string | undefined) => Annotation;
+/** Symbol for header parameter annotation */
+export declare const headerParamSymbol: unique symbol;
+/**
+ * HeaderParam trait - marks a field as a header parameter.
+ * Specify the header name.
+ *
+ * @example
+ * ```ts
+ * const Input = Schema.Struct({
+ *   apiToken: Schema.String.pipe(T.HeaderParam("X-API-Token")),
+ * });
+ * ```
+ */
+export declare const HeaderParam: (name: string) => Annotation;
+/**
+ * HttpPath - alias for PathParam that also carries the wire name.
+ * Used in generated code: `Schema.String.pipe(T.HttpPath("account_id"))`
+ */
+export declare const HttpPath: (name: string) => Annotation;
+/**
+ * HttpQuery - alias for QueryParam with an explicit wire name.
+ * Used in generated code: `Schema.optional(Schema.String).pipe(T.HttpQuery("per_page"))`
+ */
+export declare const HttpQuery: (name: string) => Annotation;
+/**
+ * HttpHeader - alias for HeaderParam.
+ * Used in generated code: `Schema.String.pipe(T.HttpHeader("X-Custom-Header"))`
+ */
+export declare const HttpHeader: (name: string) => Annotation;
+/** Symbol for HTTP body annotation */
+export declare const httpBodySymbol: unique symbol;
+/**
+ * HttpBody - marks a field as the raw HTTP body.
+ * Used for operations where a field IS the entire request body
+ * (not a named field within a JSON body).
+ */
+export declare const HttpBody: () => Annotation;
+/** Symbol for form data file annotation */
+export declare const httpFormDataFileSymbol: unique symbol;
+/**
+ * HttpFormDataFile - marks a field as a file upload in multipart form data.
+ */
+export declare const HttpFormDataFile: () => Annotation;
+/** Symbol for API error code mapping */
+export declare const apiErrorCodeSymbol: unique symbol;
+/**
+ * ApiErrorCode trait - maps an error class to an API error code.
+ * Used to match API error responses to typed error classes.
+ *
+ * @example
+ * ```ts
+ * class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()(
+ *   "NotFoundError",
+ *   { message: Schema.String },
+ * ).pipe(T.ApiErrorCode("not_found")) {}
+ * ```
+ */
+export declare const ApiErrorCode: (code: string) => Annotation;
+/** Symbol for service metadata */
+export declare const serviceSymbol: unique symbol;
+/** Service metadata */
+export interface ServiceTrait {
+    name: string;
+    version?: string;
+    baseUrl?: string;
+    /** GCP-specific: Root URL for the service */
+    rootUrl?: string;
+    /** GCP-specific: Service path appended to root URL */
+    servicePath?: string;
+    /** Allow additional properties for provider-specific metadata */
+    [key: string]: unknown;
+}
+/**
+ * Service trait - attaches service metadata to a schema.
+ */
+export declare const Service: (trait: ServiceTrait) => Annotation;
+/**
+ * Get annotation value from an AST node, following encoding chain if needed.
+ */
+export declare const getAnnotation: <T>(ast: AST.AST, symbol: symbol) => T | undefined;
+/**
+ * Get HTTP trait from a schema's AST.
+ */
+export declare const getHttpTrait: (ast: AST.AST) => HttpTrait | undefined;
+/**
+ * Check if a PropertySignature has the pathParam annotation.
+ * Works for both PathParam() (annotation value = true) and HttpPath("wire_name") (annotation value = string).
+ */
+export declare const isPathParam: (prop: AST.PropertySignature) => boolean;
+/**
+ * Get query param name from a PropertySignature (returns true if unnamed, string if named).
+ */
+export declare const getQueryParam: (prop: AST.PropertySignature) => string | boolean | undefined;
+/**
+ * Get header param name from a PropertySignature.
+ */
+export declare const getHeaderParam: (prop: AST.PropertySignature) => string | undefined;
+/**
+ * Get API error code from an error class AST.
+ */
+export declare const getApiErrorCode: (ast: AST.AST) => string | undefined;
+/**
+ * Get service metadata from a schema's AST.
+ */
+export declare const getServiceTrait: (ast: AST.AST) => ServiceTrait | undefined;
+/**
+ * Extract path parameters from a schema's struct properties.
+ * Returns an array of field names that have the PathParam annotation.
+ */
+export declare const getPathParams: (ast: AST.AST) => string[];
+/**
+ * Build the request path by substituting path parameters into the template.
+ * Simple version that assumes input keys match template placeholders.
+ * For schema-aware path building (with camelCase → wire_name mapping), use buildPathFromSchema.
+ */
+export declare const buildPath: (template: string, input: Record<string, unknown>) => string;
+/**
+ * Extract AST property signatures from a schema AST, following encoding chain and suspends.
+ */
+export declare const getStructProps: (ast: AST.AST) => AST.PropertySignature[];
+/**
+ * Get the path parameter wire name from a PropertySignature.
+ * - For HttpPath("wire_name"), returns the wire name string.
+ * - For PathParam(), returns the property name (since annotation is `true`).
+ * - Returns undefined if not a path param.
+ */
+export declare const getPathParamWireName: (prop: AST.PropertySignature) => string | undefined;
+/**
+ * Result of categorizing a schema's input properties by their HTTP binding.
+ */
+export interface RequestParts {
+    /** Resolved path with all parameters substituted */
+    path: string;
+    /** Query parameters: wire_name → string value */
+    query: Record<string, string | string[]>;
+    /** Header parameters: header-name → string value */
+    headers: Record<string, string>;
+    /** Body: remaining non-path/query/header properties, with wire-name keys where applicable */
+    body: Record<string, unknown> | undefined;
+    /** Whether the body should use multipart/form-data */
+    isMultipart: boolean;
+}
+/**
+ * Schema-aware request builder. Categorizes input properties into path, query, header,
+ * and body parts using annotations on the schema AST.
+ *
+ * Handles camelCase → wire_name mapping for path params (HttpPath), query params (HttpQuery),
+ * and header params (HttpHeader).
+ *
+ * When `inputSchema` is provided, uses `Schema.encodeSync` to encode the input through the
+ * schema's encoding pipeline (e.g., `encodeKeys` for camelCase → snake_case mapping).
+ * The encoded output is used for body construction, ensuring wire-format key names.
+ */
+export declare const buildRequestParts: (ast: AST.AST, httpTrait: HttpTrait, input: Record<string, unknown>, inputSchema?: any) => RequestParts;
+/**
+ * Helper to get a value from an object using a dot-separated path.
+ * Used for pagination traits and nested property access.
+ */
+export declare const getPath: (obj: unknown, path: string) => unknown;
+export {};
+//# sourceMappingURL=traits.d.ts.map

package/lib/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"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"}