@apollo-deploy/tesseract 0.9.1 → 1.2.0

package/dist/types/sdk-module.d.ts

@@ -31,7 +31,7 @@ export interface SDKModuleConfig {
      *
      * @default 'stable'
      */
-    stability?: 'stable' | 'experimental' | 'internal';
+    stability?: "stable" | "experimental" | "internal";
 }
 /** Symbol used to store SDKModuleConfig on a decorated class. */
 export declare const SDK_MODULE_CONFIG: unique symbol;
@@ -89,7 +89,7 @@ export interface SDKRouteConfig {
     /** Override the generated method name for this route. */
     methodName?: string;
     /** Request body encoding. Defaults to `'json'`. */
-    transport?: 'json' | 'multipart' | 'binary' | 'stream';
+    transport?: "json" | "multipart" | "binary" | "stream";
     /** Completely exclude this route from the generated SDK. */
     exclude?: boolean;
     /**
@@ -124,5 +124,25 @@ export interface SDKRouteConfig {
      * wrapper. e.g. `"SignalStreamEvent"` emits `AsyncIterable<SignalStreamEvent>`.
      */
     sseReturnType?: string;
+    /**
+     * Override the generated return type for this route.
+     *
+     * Useful for paginated list endpoints where the response body is a wrapper
+     * object (e.g. `{ data: T[], page: PageMeta }`) but the SDK consumer only
+     * cares about the inner array type.
+     *
+     * @example
+     * ```ts
+     * sdk: {
+     *   methodName: 'listProjects',
+     *   returnType: 'SignalProjectSchema[]',
+     * }
+     * ```
+     *
+     * The value is emitted verbatim as the `Promise<T>` type parameter.
+     * Type names are automatically collected for imports when they match
+     * known schema names.
+     */
+    returnType?: string;
 }
 //# sourceMappingURL=sdk-module.d.ts.map

package/dist/types/sdk-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-module.d.ts","sourceRoot":"","sources":["../../src/types/sdk-module.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,cAAc,GAAG,UAAU,CAAC;CACpD;AAED,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,eAAsC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,IACvC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAC5D,QAAQ,CAAC,EACT,UAAU,qBAAqB,CAAC,CAAC,CAAC,KACjC,IAAI,CAUR;AAGD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEvD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAE9B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IAEH;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"sdk-module.d.ts","sourceRoot":"","sources":["../../src/types/sdk-module.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,cAAc,GAAG,UAAU,CAAC;CACpD;AAED,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,eAAsC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,IACvC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAC5D,QAAQ,CAAC,EACT,UAAU,qBAAqB,CAAC,CAAC,CAAC,KACjC,IAAI,CAUR;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEvD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAE9B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IAEH;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/sdk-module.js

@@ -1,5 +1,5 @@
 /** Symbol used to store SDKModuleConfig on a decorated class. */
-export const SDK_MODULE_CONFIG = Symbol('tesseract:sdkModuleConfig');
+export const SDK_MODULE_CONFIG = Symbol("tesseract:sdkModuleConfig");
 /**
  * Module-level domain registry. Populated by `@SDKModule` and `sdkDomain()`.
  * Read by the Fastify plugin at generation time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollo-deploy/tesseract",
-  "version": "0.9.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Manifest-first SDK generator — turns sdk-manifold/v1 manifests into production-ready TypeScript SDKs",
   "bin": {

package/templates/csharp/client.hbs

@@ -0,0 +1,95 @@
+namespace {{namespace}};
+
+using System;
+using System.Collections.Generic;
+using {{namespace}}.Api;
+
+/// <summary>
+/// Configuration for the {{clientName}} API client.
+/// </summary>
+public class {{clientName}}ClientConfig
+{
+    /// <summary>
+    /// Base URL for all API requests.
+    /// </summary>
+    public string BaseUrl { get; set; } = "{{baseUrl}}";
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+    /// <summary>
+    /// API key for the {{name}} security scheme.
+    /// </summary>
+    public string? {{pascalCase configKey}} { get; set; }
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+    /// <summary>
+    /// Bearer token for the {{name}} security scheme.
+    /// </summary>
+    public string? {{pascalCase configKey}} { get; set; }
+{{/if}}
+{{#if (eq type "oauth2")}}
+    /// <summary>
+    /// OAuth2 access token for the {{name}} security scheme.
+    /// </summary>
+    public string? {{pascalCase configKey}} { get; set; }
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+    /// <summary>
+    /// OpenID Connect token for the {{name}} security scheme.
+    /// </summary>
+    public string? {{pascalCase configKey}} { get; set; }
+{{/if}}
+{{/each}}
+    /// <summary>
+    /// Request timeout in milliseconds.
+    /// </summary>
+    public int TimeoutMs { get; set; } = 15000;
+
+    /// <summary>
+    /// Maximum number of retry attempts for transient failures.
+    /// </summary>
+    public int MaxRetries { get; set; } = 3;
+
+    /// <summary>
+    /// Default headers sent with every request.
+    /// </summary>
+    public Dictionary<string, string>? DefaultHeaders { get; set; }
+}
+
+/// <summary>
+/// Primary API client for {{title}}.
+/// </summary>
+public class {{clientName}}Client
+{
+    private readonly Transport _transport;
+
+{{#each groups}}
+    /// <summary>
+    /// {{#if description}}{{description}}{{else}}{{name}} operations{{/if}}
+    /// </summary>
+    public {{interfaceName}} {{pascalCase name}} { get; }
+{{/each}}
+
+    /// <summary>
+    /// Creates a new {{clientName}} API client.
+    /// </summary>
+    /// <param name="config">Client configuration. If null, defaults are used.</param>
+    public {{clientName}}Client({{clientName}}ClientConfig? config = null)
+    {
+        config ??= new {{clientName}}ClientConfig();
+
+        _transport = new Transport(new TransportConfig
+        {
+            BaseUrl = config.BaseUrl,
+{{#each securitySchemes}}
+            {{pascalCase configKey}} = config.{{pascalCase configKey}},
+{{/each}}
+            TimeoutMs = config.TimeoutMs,
+            MaxRetries = config.MaxRetries,
+            DefaultHeaders = config.DefaultHeaders,
+        });
+
+{{#each groups}}
+        {{pascalCase name}} = new {{interfaceName}}(_transport);
+{{/each}}
+    }
+}

package/templates/csharp/csproj.hbs

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <PackageId>{{packageName}}</PackageId>
+    <Version>{{packageVersion}}</Version>
+    <Description>{{#if description}}{{description}}{{else}}C# SDK for {{title}}{{/if}}</Description>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <RootNamespace>{{namespace}}</RootNamespace>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.Text.Json" Version="8.0.*" />
+  </ItemGroup>
+
+</Project>

package/templates/csharp/domain.hbs

@@ -0,0 +1,183 @@
+namespace {{namespace}}.Api;
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+/// <summary>
+/// Provides access to {{name}} API operations.
+/// </summary>
+public class {{interfaceName}}
+{
+    private readonly Transport _transport;
+
+    /// <summary>
+    /// Creates a new {{interfaceName}} instance.
+    /// </summary>
+    public {{interfaceName}}(Transport transport)
+    {
+        _transport = transport;
+    }
+
+{{#each operations}}
+{{#if isEventStream}}
+    /// <summary>
+    {{#if summary}}
+    /// {{summary}}
+    {{/if}}
+    {{#if description}}
+    /// {{description}}
+    {{/if}}
+    {{#if deprecated}}
+    /// [Obsolete] {{#if deprecationMessage}}{{deprecationMessage}}{{/if}}
+    {{/if}}
+    /// </summary>
+{{#if deprecated}}
+    [Obsolete({{#if deprecationMessage}}"{{deprecationMessage}}"{{/if}})]
+{{/if}}
+    public async IAsyncEnumerable<string> {{pascalCase name}}Async(
+{{#each pathParams}}
+        {{type}}{{#if (not required)}}?{{/if}} {{name}},
+{{/each}}
+{{#if requestBody}}
+        {{requestBody.type}}{{#if (not requestBody.required)}}?{{/if}} body,
+{{/if}}
+{{#if queryType}}
+        {{queryType}}? query = null,
+{{/if}}
+        CancellationToken cancellationToken = default)
+    {
+        var path = $"{{path}}"
+{{#each pathParams}}
+            .Replace("{{{originalName}}}", Uri.EscapeDataString({{name}}?.ToString() ?? ""))
+{{/each}}
+        ;
+
+        var queryParams = new Dictionary<string, string>();
+{{#if queryType}}
+        if (query != null)
+        {
+            var json = JsonSerializer.Serialize(query);
+            var dict = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(json);
+            if (dict != null)
+            {
+                foreach (var (key, value) in dict)
+                {
+                    if (value.ValueKind != JsonValueKind.Null)
+                        queryParams[key] = value.ToString();
+                }
+            }
+        }
+{{/if}}
+{{#if (hasQueryParams this)}}
+{{#each queryParams}}
+        if ({{name}} != null)
+            queryParams["{{originalName}}"] = {{name}}.ToString();
+{{/each}}
+{{/if}}
+
+        var response = await _transport.StreamAsync(
+            new Transport.Request
+            {
+                Method = HttpMethod.{{httpMethod}},
+                Path = path,
+                Query = queryParams.Count > 0 ? queryParams : null,
+{{#if requestBody}}
+                Body = body,
+                ContentType = "{{requestBody.contentType}}",
+{{/if}}
+            },
+            cancellationToken);
+
+        using var stream = await response.Content.ReadAsStreamAsync(cancellationToken);
+        using var reader = new StreamReader(stream);
+
+        while (!reader.EndOfStream)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var line = await reader.ReadLineAsync(cancellationToken);
+            if (line == null) break;
+
+            // Forward raw SSE lines
+            yield return line;
+        }
+    }
+
+{{else}}
+    /// <summary>
+    {{#if summary}}
+    /// {{summary}}
+    {{/if}}
+    {{#if description}}
+    /// {{description}}
+    {{/if}}
+    {{#if deprecated}}
+    /// [Obsolete] {{#if deprecationMessage}}{{deprecationMessage}}{{/if}}
+    {{/if}}
+    /// </summary>
+{{#if deprecated}}
+    [Obsolete({{#if deprecationMessage}}"{{deprecationMessage}}"{{/if}})]
+{{/if}}
+    public async Task<{{#if responseType}}{{responseType}}{{else}}object{{/if}}> {{pascalCase name}}Async(
+{{#each pathParams}}
+        {{type}}{{#if (not required)}}?{{/if}} {{name}},
+{{/each}}
+{{#if requestBody}}
+        {{requestBody.type}}{{#if (not requestBody.required)}}?{{/if}} body,
+{{/if}}
+{{#if queryType}}
+        {{queryType}}? query = null,
+{{/if}}
+        CancellationToken cancellationToken = default)
+    {
+        var path = $"{{path}}"
+{{#each pathParams}}
+            .Replace("{{{originalName}}}", Uri.EscapeDataString({{name}}?.ToString() ?? ""))
+{{/each}}
+        ;
+
+        var queryParams = new Dictionary<string, string>();
+{{#if queryType}}
+        if (query != null)
+        {
+            var json = JsonSerializer.Serialize(query);
+            var dict = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(json);
+            if (dict != null)
+            {
+                foreach (var (key, value) in dict)
+                {
+                    if (value.ValueKind != JsonValueKind.Null)
+                        queryParams[key] = value.ToString();
+                }
+            }
+        }
+{{/if}}
+{{#if (hasQueryParams this)}}
+{{#each queryParams}}
+        if ({{name}} != null)
+            queryParams["{{originalName}}"] = {{name}}.ToString();
+{{/each}}
+{{/if}}
+
+        return await _transport.ExecuteAsync<{{#if responseType}}{{responseType}}{{else}}object{{/if}}>(
+            new Transport.Request
+            {
+                Method = HttpMethod.{{httpMethod}},
+                Path = path,
+                Query = queryParams.Count > 0 ? queryParams : null,
+{{#if requestBody}}
+                Body = body,
+                ContentType = "{{requestBody.contentType}}",
+{{/if}}
+            },
+            cancellationToken);
+    }
+
+{{/if}}
+{{/each}}
+}

package/templates/csharp/errors.hbs

@@ -0,0 +1,45 @@
+namespace {{namespace}};
+
+using System;
+
+/// <summary>
+/// Represents an error returned by the API.
+/// </summary>
+public class SdkException : Exception
+{
+    /// <summary>
+    /// HTTP status code.
+    /// </summary>
+    public int Status { get; }
+
+    /// <summary>
+    /// Machine-readable error code from the API.
+    /// </summary>
+    public string? Code { get; }
+
+    /// <summary>
+    /// Unique request identifier for support.
+    /// </summary>
+    public string? RequestId { get; }
+
+    /// <summary>
+    /// Creates a new SdkException.
+    /// </summary>
+    public SdkException(int status, string? code, string message, string? requestId, Exception? innerException = null)
+        : base(message, innerException)
+    {
+        Status = status;
+        Code = code;
+        RequestId = requestId;
+    }
+
+    /// <summary>
+    /// Returns a string representation of the error.
+    /// </summary>
+    public override string ToString()
+    {
+        if (!string.IsNullOrEmpty(Code))
+            return $"[{Status}] {Code}: {Message}";
+        return $"[{Status}] {Message}";
+    }
+}

package/templates/csharp/readme.hbs

@@ -0,0 +1,76 @@
+# {{title}} .NET SDK
+
+[![NuGet](https://img.shields.io/nuget/v/{{packageName}}.svg)](https://www.nuget.org/packages/{{packageName}}/)
+
+The official .NET SDK for {{#if description}}{{description}}{{else}}the {{title}} API{{/if}}.
+
+## Installation
+
+```bash
+dotnet add package {{packageName}}
+```
+
+## Quick Start
+
+```csharp
+using {{namespace}};
+
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+var config = new {{../clientName}}ClientConfig
+{
+    {{pascalCase configKey}} = "your-api-key"{{#if (and (eq type "apiKey") (eq in "header"))}}{{/if}}
+};
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+var config = new {{../clientName}}ClientConfig
+{
+    {{pascalCase configKey}} = "your-bearer-token"
+};
+{{/if}}
+{{/each}}
+{{#unless securitySchemes.length}}
+var config = new {{clientName}}ClientConfig();
+{{/unless}}
+
+var client = new {{clientName}}Client(config);
+
+{{#each groups}}
+{{#with operations.[0]}}
+// {{../interfaceName}}.{{pascalCase name}} example
+var result = await client.{{pascalCase ../name}}.{{pascalCase name}}Async({{#each ../pathParams}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}{{#if requestBody}}{{#if ../pathParams.length}}, {{/if}}new {{requestBody.type}}(){}{{/if}});
+Console.WriteLine(result);
+{{/with}}
+{{/each}}
+```
+
+## API Reference
+
+| Domain | Description |
+|--------|-------------|
+{{#each groups}}
+| `{{interfaceName}}` | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
+{{/each}}
+
+## Error Handling
+
+All async methods throw `SdkException` on API errors. Use try-catch to handle errors:
+
+```csharp
+try
+{
+    var result = await client.{{#each groups}}{{#if @first}}{{pascalCase name}}{{/if}}{{/each}}.{{#each groups}}{{#if @first}}{{#with operations.[0]}}{{pascalCase name}}Async(){{/with}}{{/if}}{{/each}};
+}
+catch (SdkException ex)
+{
+    Console.WriteLine($"Status: {ex.Status}, Code: {ex.Code}, RequestId: {ex.RequestId}");
+}
+```
+
+## Requirements
+
+- .NET 8.0 or later
+
+## License
+
+{{#if license}}{{license}}{{else}}MIT{{/if}}