@trayai/helix-sdk 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -8,6 +8,20 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The SDK and [`@trayai/helix-cli`](https://www.npmjs.com/package/@trayai/helix-cli) are
 released together and share a version — install matching versions.
 
+## 1.6.0
+
+### Changed
+
+- Internal `@trayai/helix-sdk/broker` additions supporting the Helix CLI's new
+  `tray_list_authentication_templates` MCP tool. No changes to the SDK's public API
+  (`ctx.http`/`ctx.kv`/`ctx.files`, config, `/testing`).
+
+### Documentation
+
+- The README now has a "Connecting any API" guide: how to connect an API that is not in the
+  supported list using **HTTP Bearer Token**, **HTTP Basic Authentication** or **Custom Token
+  Authentication**, and what to enter in each form.
+
 ## 1.4.0
 
 ### Changed

package/README.md

@@ -114,6 +114,39 @@ Each method returns `{ status, body?, headers }`. An upstream non-2xx response i
 - Redirects are not followed: a 3xx response is returned to your code with its `location` header, and following it is your decision. Plain `ctx.http` also stops auto-following redirects, but — unlike this authed client — it throws for a 3xx by default like any other non-2xx status; pass `{ throwHttpErrors: false }` to get it back as a value instead.
 - An unknown alias throws `SdkError.unknownAlias` (the error lists the configured aliases).
 
+### Connecting any API: the generic services
+
+You are not limited to the services offered in the dashboard's service picker. If your API is not there and it authenticates with a token, an API key or a username and password, create the authentication against one of the generic services below, then call it exactly like any other alias with `ctx.http.authed(alias)`. The platform adds the credential to the request; the secret never reaches your code.
+
+| If the API expects… | Pick |
+|---------------------|------|
+| `Authorization: Bearer <token>` | **HTTP Bearer Token** |
+| A username and password (or an API token used as the password) | **HTTP Basic Authentication** |
+| A token or API key in a header you name, or in the query string | **Custom Token Authentication** |
+
+**How to create one**
+
+1. Run `helix auth connect --new` (it opens the Helix dashboard for your workspace; use `--no-open` to print the link instead). In the dashboard, choose the generic service and fill in the form.
+2. Back in the terminal the CLI finds the new authentication and writes the alias into `helix.config.ts` for you. (If you run it without a terminal, it only prints the link: connect the authentication afterwards with `helix auth connect` or `helix auth add <alias> <uuid>`.)
+3. Call it: `await ctx.http.authed('my_api').get('https://api.vendor.com/v1/things')`.
+
+**What to enter in the form**
+
+*HTTP Bearer Token* and *HTTP Basic Authentication*: the token, or the username and password.
+
+*Custom Token Authentication*
+
+| Field | Value |
+|-------|-------|
+| Token | The API key or token |
+| Location | `header` (the default) or `query` (the query string) |
+| Location Value | The header name (for example `X-Api-Key`) or the query parameter (for example `api_key`) |
+| Pin to domain | Optional but recommended: the only domain this credential may be sent to, for example `api.vendor.com` |
+
+APIs that need OAuth 1.0a, a request signature (HMAC) or AWS Signature v4 are not available as generic services yet, and neither is OAuth 2.0 sign-in with token refresh: use the service's own entry if it is offered in the dashboard.
+
+If the API answers `401`, check first that the authentication was created with the values and Location you expect.
+
 ### Signed S3 URLs — `s3Sign`
 
 For AWS/S3 authentications, the authed client can mint a **presigned S3 URL** — a time-limited URL your code (or anyone you hand it to) uses against S3 directly, with no credentials attached:

package/dist/broker/index.d.ts

@@ -1,8 +1,47 @@
 import { R as Region } from '../region-schema-COfWyGI9.js';
-import 'zod';
+import { z } from 'zod';
 
 type BrokerRegion = Region;
 
+/** JSON-format strategy names — mirrors the credential broker's own
+    JsonTemplateStrategySchema. Hand-maintained: the two repos share no build
+    dependency, so this is intentionally duplicated rather than imported. */
+declare const JSON_TEMPLATE_STRATEGIES: readonly ["bearer", "api-key-header", "api-key-query", "basic", "oauth1", "aws-sigv4", "hmac", "custom"];
+type JsonTemplateStrategy = (typeof JSON_TEMPLATE_STRATEGIES)[number];
+declare const TemplatesResponseSchema: z.ZodObject<{
+    templates: z.ZodArray<z.ZodObject<{
+        serviceName: z.ZodString;
+        serviceVersion: z.ZodNumber;
+        authenticationType: z.ZodString;
+        strategy: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        serviceName: string;
+        serviceVersion: number;
+        authenticationType: string;
+        strategy?: string | undefined;
+    }, {
+        serviceName: string;
+        serviceVersion: number;
+        authenticationType: string;
+        strategy?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    templates: {
+        serviceName: string;
+        serviceVersion: number;
+        authenticationType: string;
+        strategy?: string | undefined;
+    }[];
+}, {
+    templates: {
+        serviceName: string;
+        serviceVersion: number;
+        authenticationType: string;
+        strategy?: string | undefined;
+    }[];
+}>;
+type TemplatesResponse = z.infer<typeof TemplatesResponseSchema>;
+
 interface BrokerDevCallParams {
     /** Target Tray region — selects the broker base URL. */
     env: BrokerRegion;
@@ -109,5 +148,37 @@ type S3SignDevCallResult = {
  * explicitly.
  */
 declare function callS3SignDev(params: S3SignDevCallParams): Promise<S3SignDevCallResult>;
+interface TemplatesDevCallParams {
+    /** Target Tray region — selects the broker base URL. */
+    env: BrokerRegion;
+    /** Personal dev token (the user's local Tray login) sent as `Authorization: Bearer`. */
+    devToken: string;
+    timeoutMs?: number;
+}
+/**
+ * Result of a one-shot dev templates-discovery call.
+ * - `templates` — the registered (serviceName, serviceVersion,
+ *   authenticationType, strategy?) keys.
+ * - `brokerError` — a broker-generated error.
+ */
+type TemplatesDevCallResult = {
+    kind: "templates";
+    templates: TemplatesResponse["templates"];
+} | {
+    kind: "brokerError";
+    brokerStatus: number;
+    code?: string;
+    body: unknown;
+};
+/**
+ * Stateless, one-shot call to the credential broker's authentication-template
+ * discovery dev endpoint (`GET /private/v1/helix/authentications/templates/dev`).
+ *
+ * Factored out the same way `callS3SignDev`/`callBrokerDev` are, so CLI
+ * tooling (the `tray_list_authentication_templates` MCP tool) can list what
+ * auth mechanism the broker will apply for a given service without booting
+ * the dev server. Reads no module-global state.
+ */
+declare function callTemplatesDev(params: TemplatesDevCallParams): Promise<TemplatesDevCallResult>;
 
-export { type BrokerDevCallParams, type BrokerDevCallResult, type BrokerRegion, type S3SignDevCallParams, type S3SignDevCallResult, type UpstreamResponse, callBrokerDev, callS3SignDev };
+export { type BrokerDevCallParams, type BrokerDevCallResult, type BrokerRegion, type JsonTemplateStrategy, type S3SignDevCallParams, type S3SignDevCallResult, type TemplatesDevCallParams, type TemplatesDevCallResult, type UpstreamResponse, callBrokerDev, callS3SignDev, callTemplatesDev };

package/dist/broker/index.js

@@ -1 +1 @@
-import{B as n,D as o,F as i,G as s,H as d,I as u,J as l}from"../chunk-3T2WZMJJ.js";async function a(e){let r=o({authenticationId:e.authenticationId,method:e.method,url:e.url,body:e.body,headers:e.headers,query:e.query}),t=await s({proxyUrl:n(e.env,"dev"),credentialHeaders:{Authorization:`Bearer ${e.devToken}`},request:r,timeoutMs:e.timeoutMs??i});return t.kind==="brokerError"?{kind:"brokerError",brokerStatus:t.status,code:t.code,body:t.body}:{kind:"upstream",upstream:t.response}}async function k(e){d(e.url);let r=await l({signUrl:u(e.env,"dev"),credentialHeaders:{Authorization:`Bearer ${e.devToken}`},body:{authenticationId:e.authenticationId,url:e.url,...e.method!==void 0?{method:e.method}:{},...e.expiresIn!==void 0?{expiresIn:e.expiresIn}:{}},timeoutMs:e.timeoutMs});return r.kind==="brokerError"?{kind:"brokerError",brokerStatus:r.status,code:r.code,body:r.body}:{kind:"signed",signed:r.result}}export{a as callBrokerDev,k as callS3SignDev};
+import{A as u,B as d,D as p,F as m,G as c,H as k,I as g,J as b,j as l}from"../chunk-3T2WZMJJ.js";import{z as s}from"zod";function v(e,t){let r=`${l(e).hosts.api}/private/v1/helix/authentications/templates`;return t==="dev"?`${r}/dev`:r}var h=s.object({templates:s.array(s.object({serviceName:s.string(),serviceVersion:s.number().int(),authenticationType:s.string(),strategy:s.string().optional()}))}),S=3e4;async function y(e){let t=new Headers;for(let[n,T]of Object.entries(e.credentialHeaders))t.set(n,T);let r=await fetch(e.templatesUrl,{method:"GET",headers:t,redirect:"manual",signal:AbortSignal.timeout(e.timeoutMs??S)}),a=await r.text(),o=a;try{o=JSON.parse(a)}catch{}if(r.ok){let n=h.safeParse(o);return n.success?{kind:"templates",result:n.data}:{kind:"brokerError",status:r.status,message:"malformed templates-discovery response",body:o}}let i=u.safeParse(o);return i.success?{kind:"brokerError",status:r.status,code:i.data.error.code,message:i.data.error.message,body:o}:{kind:"brokerError",status:r.status,message:a||`templates-discovery request failed with status ${r.status}`,body:o}}async function R(e){let t=p({authenticationId:e.authenticationId,method:e.method,url:e.url,body:e.body,headers:e.headers,query:e.query}),r=await c({proxyUrl:d(e.env,"dev"),credentialHeaders:{Authorization:`Bearer ${e.devToken}`},request:t,timeoutMs:e.timeoutMs??m});return r.kind==="brokerError"?{kind:"brokerError",brokerStatus:r.status,code:r.code,body:r.body}:{kind:"upstream",upstream:r.response}}async function f(e){k(e.url);let t=await b({signUrl:g(e.env,"dev"),credentialHeaders:{Authorization:`Bearer ${e.devToken}`},body:{authenticationId:e.authenticationId,url:e.url,...e.method!==void 0?{method:e.method}:{},...e.expiresIn!==void 0?{expiresIn:e.expiresIn}:{}},timeoutMs:e.timeoutMs});return t.kind==="brokerError"?{kind:"brokerError",brokerStatus:t.status,code:t.code,body:t.body}:{kind:"signed",signed:t.result}}async function x(e){let t=await y({templatesUrl:v(e.env,"dev"),credentialHeaders:{Authorization:`Bearer ${e.devToken}`},timeoutMs:e.timeoutMs});return t.kind==="brokerError"?{kind:"brokerError",brokerStatus:t.status,code:t.code,body:t.body}:{kind:"templates",templates:t.result.templates}}export{R as callBrokerDev,f as callS3SignDev,x as callTemplatesDev};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayai/helix-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Helix SDK runtime — defineFunction, ctx, defineConfig, authed HTTP",
   "license": "Apache-2.0",
   "author": "trayio",