@inferencesh/app 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -4,8 +4,8 @@ export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js"
 export type { Socket, Frame } from "./socket.js";
 export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, CLEAR_KEY, ERROR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
 export type { Update } from "./stream.js";
-export { meta } from "./meta.js";
-export type { FunctionMeta } from "./meta.js";
+export { meta, normalizeCredentials, CREDENTIAL_KEYS, PROVIDER_SEED_KEYS } from "./meta.js";
+export type { FunctionMeta, NormalizedFunctionMeta, CredentialEntry, CredentialsDeclaration } from "./meta.js";
 export { StorageDir, ensureDir } from "./storage.js";
 export type { StorageDirValue } from "./storage.js";
 export { download } from "./download.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export { File } from "./file.js";
 export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, CLEAR_KEY, ERROR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
 // Per-function metadata: credentials and annotations (<PascalName>Meta exports)
-export { meta } from "./meta.js";
+export { meta, normalizeCredentials, CREDENTIAL_KEYS, PROVIDER_SEED_KEYS } from "./meta.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

package/dist/meta.d.ts

@@ -18,25 +18,58 @@
  * export class App { async createEvent(input) { ... } }
  * ```
  */
-import type { CredentialRequirement, ToolAnnotations } from "./types.js";
+import type { CredentialRequirement, ProviderSeed, ToolAnnotations } from "./types.js";
+/**
+ * One credential entry as an app may write it: the current keys, plus the
+ * older spellings (`provider` as a string, `key` as a capability, `name`
+ * and `website`) which are folded into the current ones.
+ */
+export interface CredentialEntry extends Omit<CredentialRequirement, "provider"> {
+    provider?: string | ProviderSeed;
+    /** Older: a capability such as `google.calendar.events`. */
+    key?: string;
+    /** Older: the provider's display name (now `provider.name`). */
+    name?: string;
+    /** Older: the provider's site (now `provider.website`). */
+    website?: string;
+}
+/**
+ * The credentials a function needs, in any accepted form: a map keyed by
+ * credential slug, or a list of entries or bare slugs (a dotted string is a
+ * capability).
+ */
+export type CredentialsDeclaration = Record<string, CredentialEntry | null | undefined> | Array<string | CredentialEntry>;
 export interface FunctionMeta {
     /**
      * The credentials this function needs at run time. Each entry must be
      * covered by the app-wide `credentials:` in inf.yml. A function without
      * this gets the app-wide list.
      */
-    credentials?: CredentialRequirement[];
+    credentials?: CredentialsDeclaration;
     /** Hints about the function's behavior (read-only, destructive, ...). */
     annotations?: ToolAnnotations;
 }
+/** What `meta()` returns: credentials normalised to the shape the engine writes. */
+export interface NormalizedFunctionMeta {
+    credentials?: CredentialRequirement[];
+    annotations?: ToolAnnotations;
+}
+export declare const CREDENTIAL_KEYS: readonly ["slug", "capabilities", "description", "optional", "secrets", "scopes", "provider", "auth"];
+export declare const PROVIDER_SEED_KEYS: readonly ["slug", "name", "description", "website", "logo_uri", "docs_uri", "tos_uri", "policy_uri"];
+/**
+ * Every accepted form of a credentials declaration as the list the engine
+ * writes: entries in canonical key order, legacy keys folded in.
+ */
+export declare function normalizeCredentials(credentials: unknown, where?: string): CredentialRequirement[];
 /**
- * Declares a function's metadata and returns `m` unchanged. Editors
+ * Declares a function's metadata. Credentials come back normalised to the
+ * shape the engine writes (keyed by slug, legacy keys folded in), the same
+ * as sdk-py's `@function`; annotations are returned as given. Editors
  * type-check the declaration, plain `.js` apps included (with `// @ts-check`).
  *
- * Throws on a malformed declaration, at import time, with the same checks as
- * sdk-py's `@function`: an empty `credentials` list (omit it to use the
- * app-wide list from inf.yml), unknown keys, wrong value types, or a
- * credential with neither `key` nor `provider`. A null hint means
- * "not declared"; the schema omits it.
+ * Throws on a malformed declaration, at import time: an empty `credentials`
+ * declaration (omit it to use the app-wide list from inf.yml), unknown keys,
+ * wrong value types, or an entry with neither a slug nor a capability. A
+ * null hint means "not declared"; the schema omits it.
  */
-export declare function meta(m: FunctionMeta): FunctionMeta;
+export declare function meta(m: FunctionMeta): NormalizedFunctionMeta;

package/dist/meta.js

@@ -18,23 +18,57 @@
  * export class App { async createEvent(input) { ... } }
  * ```
  */
-const CREDENTIAL_STR_KEYS = ["provider", "name", "website", "key", "description"];
-const CREDENTIAL_LIST_KEYS = ["secrets", "scopes"];
-const CREDENTIAL_KEYS = [...CREDENTIAL_STR_KEYS, "optional", ...CREDENTIAL_LIST_KEYS];
+// The entry as written to functions_schema.json, in this key order.
+export const CREDENTIAL_KEYS = ["slug", "capabilities", "description", "optional", "secrets", "scopes", "provider", "auth"];
+export const PROVIDER_SEED_KEYS = ["slug", "name", "description", "website", "logo_uri", "docs_uri", "tos_uri", "policy_uri"];
+// Older spellings, read and folded into the keys above.
+const LEGACY_CREDENTIAL_KEYS = ["key", "name", "website"];
+const CREDENTIAL_STR_KEYS = ["slug", "description"];
+const CREDENTIAL_LIST_KEYS = ["capabilities", "secrets", "scopes"];
 const ANNOTATION_HINT_KEYS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
 const ANNOTATION_KEYS = ["title", ...ANNOTATION_HINT_KEYS];
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const typeName = (v) => (v === null ? "null" : Array.isArray(v) ? "array" : typeof v);
 const unknownKeys = (obj, allowed) => Object.keys(obj).filter((k) => !allowed.includes(k)).sort();
-function checkCredential(i, entry) {
-    const where = `meta() credentials[${i}]`;
+function strList(where, k, v) {
+    if (!(Array.isArray(v) && v.every((s) => typeof s === "string"))) {
+        throw new TypeError(`${where}.${k}: expected a list of strings`);
+    }
+    return [...v];
+}
+/** A bare string: a credential slug, or a capability when dotted. */
+function entryFromRef(ref) {
+    return ref.includes(".") ? { key: ref } : { slug: ref };
+}
+function checkProviderSeed(where, seed) {
+    if (!isObject(seed))
+        throw new TypeError(`${where}: expected an object, got ${typeName(seed)}`);
+    const unknown = unknownKeys(seed, PROVIDER_SEED_KEYS);
+    if (unknown.length > 0) {
+        throw new Error(`${where}: unknown keys ${JSON.stringify(unknown)}; allowed: ${JSON.stringify(PROVIDER_SEED_KEYS)}`);
+    }
+    const out = {};
+    for (const k of PROVIDER_SEED_KEYS) {
+        const v = seed[k];
+        if (v === undefined)
+            continue;
+        if (typeof v !== "string")
+            throw new TypeError(`${where}.${k}: expected a string, got ${typeName(v)}`);
+        if (v)
+            out[k] = v;
+    }
+    return out;
+}
+/** One entry, in any accepted spelling, as the normalised requirement. */
+function checkCredential(where, raw, slugFromKey = "") {
+    const entry = typeof raw === "string" ? entryFromRef(raw) : raw;
     if (!isObject(entry))
-        throw new TypeError(`${where}: expected an object, got ${typeName(entry)}`);
-    const unknown = unknownKeys(entry, CREDENTIAL_KEYS);
+        throw new TypeError(`${where}: expected an object or a slug, got ${typeName(entry)}`);
+    const unknown = unknownKeys(entry, [...CREDENTIAL_KEYS, ...LEGACY_CREDENTIAL_KEYS]);
     if (unknown.length > 0) {
         throw new Error(`${where}: unknown keys ${JSON.stringify(unknown)}; allowed: ${JSON.stringify(CREDENTIAL_KEYS)}`);
     }
-    for (const k of CREDENTIAL_STR_KEYS) {
+    for (const k of [...CREDENTIAL_STR_KEYS, ...LEGACY_CREDENTIAL_KEYS]) {
         if (entry[k] !== undefined && typeof entry[k] !== "string") {
             throw new TypeError(`${where}.${k}: expected a string, got ${typeName(entry[k])}`);
         }
@@ -42,15 +76,90 @@ function checkCredential(i, entry) {
     if (entry.optional !== undefined && typeof entry.optional !== "boolean") {
         throw new TypeError(`${where}.optional: expected a boolean, got ${typeName(entry.optional)}`);
     }
-    for (const k of CREDENTIAL_LIST_KEYS) {
+    let slug = typeof entry.slug === "string" ? entry.slug : "";
+    let seed = {};
+    const provider = entry.provider;
+    if (typeof provider === "string") {
+        // The older form: provider was the credential slug.
+        if (slug && provider !== slug)
+            throw new Error(`${where}: slug '${slug}' and provider '${provider}' disagree`);
+        slug = provider;
+    }
+    else if (provider !== undefined && provider !== null) {
+        seed = { ...checkProviderSeed(`${where}.provider`, provider) };
+    }
+    for (const k of ["name", "website"]) {
         const v = entry[k];
-        if (v !== undefined && !(Array.isArray(v) && v.every((s) => typeof s === "string"))) {
-            throw new TypeError(`${where}.${k}: expected a list of strings`);
+        if (typeof v === "string" && v && !seed[k])
+            seed[k] = v;
+    }
+    const capabilities = entry.capabilities !== undefined ? strList(where, "capabilities", entry.capabilities) : [];
+    const key = typeof entry.key === "string" ? entry.key : "";
+    if (key) {
+        if (key.includes(".") && !capabilities.includes(key))
+            capabilities.push(key);
+        if (!slug)
+            slug = key.split(".", 1)[0];
+    }
+    if (slugFromKey) {
+        if (slug && slug !== slugFromKey)
+            throw new Error(`${where}: entry says slug '${slug}' but is keyed as '${slugFromKey}'`);
+        slug = slugFromKey;
+    }
+    if (!slug) {
+        throw new Error(`${where}: set 'slug' (the credential slug, like 'slack') or a capability under 'capabilities'`);
+    }
+    for (const capability of capabilities) {
+        if (!capability.includes("."))
+            throw new Error(`${where}: capability '${capability}' is not <slug>.<name>`);
+    }
+    const auth = entry.auth;
+    if (auth !== undefined && auth !== null && !isObject(auth)) {
+        throw new TypeError(`${where}.auth: expected an object, got ${typeName(auth)}`);
+    }
+    const out = { slug };
+    if (capabilities.length > 0)
+        out.capabilities = capabilities;
+    if (typeof entry.description === "string" && entry.description)
+        out.description = entry.description;
+    if (entry.optional !== undefined)
+        out.optional = entry.optional;
+    for (const k of ["secrets", "scopes"]) {
+        if (entry[k] !== undefined) {
+            const v = strList(where, k, entry[k]);
+            if (v.length > 0)
+                out[k] = v;
         }
     }
-    if (!entry.key && !entry.provider) {
-        throw new Error(`${where}: set 'key' (a capability like 'google.calendar.events') or 'provider'`);
+    if (Object.keys(seed).length > 0)
+        out.provider = seed;
+    if (auth)
+        out.auth = { ...auth };
+    return out;
+}
+/**
+ * Every accepted form of a credentials declaration as the list the engine
+ * writes: entries in canonical key order, legacy keys folded in.
+ */
+export function normalizeCredentials(credentials, where = "meta() credentials") {
+    if (isObject(credentials)) {
+        const slugs = Object.keys(credentials);
+        if (slugs.length === 0)
+            throw new Error(`${where}: empty; omit credentials to use the app-wide list from inf.yml`);
+        return slugs.map((slug) => {
+            const entry = credentials[slug];
+            if (entry !== undefined && entry !== null && !isObject(entry)) {
+                throw new TypeError(`${where}['${slug}']: expected an object, got ${typeName(entry)}`);
+            }
+            return checkCredential(`${where}['${slug}']`, entry ?? {}, slug);
+        });
     }
+    if (!Array.isArray(credentials)) {
+        throw new TypeError(`${where}: expected an object keyed by slug or a list of entries, got ${typeName(credentials)}`);
+    }
+    if (credentials.length === 0)
+        throw new Error(`${where}: empty list; omit credentials to use the app-wide list from inf.yml`);
+    return credentials.map((c, i) => checkCredential(`${where}[${i}]`, c));
 }
 function checkAnnotations(annotations) {
     if (!isObject(annotations)) {
@@ -71,14 +180,15 @@ function checkAnnotations(annotations) {
     }
 }
 /**
- * Declares a function's metadata and returns `m` unchanged. Editors
+ * Declares a function's metadata. Credentials come back normalised to the
+ * shape the engine writes (keyed by slug, legacy keys folded in), the same
+ * as sdk-py's `@function`; annotations are returned as given. Editors
  * type-check the declaration, plain `.js` apps included (with `// @ts-check`).
  *
- * Throws on a malformed declaration, at import time, with the same checks as
- * sdk-py's `@function`: an empty `credentials` list (omit it to use the
- * app-wide list from inf.yml), unknown keys, wrong value types, or a
- * credential with neither `key` nor `provider`. A null hint means
- * "not declared"; the schema omits it.
+ * Throws on a malformed declaration, at import time: an empty `credentials`
+ * declaration (omit it to use the app-wide list from inf.yml), unknown keys,
+ * wrong value types, or an entry with neither a slug nor a capability. A
+ * null hint means "not declared"; the schema omits it.
  */
 export function meta(m) {
     if (!isObject(m))
@@ -87,16 +197,12 @@ export function meta(m) {
     if (unknown.length > 0) {
         throw new Error(`meta(): unknown keys ${JSON.stringify(unknown)}; allowed: ["credentials","annotations"]`);
     }
-    if (m.credentials !== undefined) {
-        if (!Array.isArray(m.credentials)) {
-            throw new TypeError(`meta() credentials: expected a list of objects, got ${typeName(m.credentials)}`);
-        }
-        if (m.credentials.length === 0) {
-            throw new Error("meta() credentials: empty list; omit credentials to use the app-wide list from inf.yml");
-        }
-        m.credentials.forEach((c, i) => checkCredential(i, c));
-    }
     if (m.annotations !== undefined)
         checkAnnotations(m.annotations);
-    return m;
+    if (m.credentials === undefined)
+        return m;
+    const out = { credentials: normalizeCredentials(m.credentials) };
+    if (m.annotations !== undefined)
+        out.annotations = m.annotations;
+    return out;
 }

package/dist/types.d.ts

@@ -12,33 +12,83 @@ export interface RequestMetadata {
     user_id: string;
 }
 /**
- * CredentialRequirement is an entry under credentials: in inf.yml: keys an
- * app needs that belong to a provider. Provider names whose credential
- * supplies them; Secrets lists the keys to inject from it (an API key
- * credential), Scopes what to ask for (an OAuth one).
+ * CredentialRequirement is an entry under credentials: in inf.yml: a
+ * credential the app uses, keyed by the credential's slug (what
+ * Credential.Provider stores). Secrets lists the keys to inject from it (an
+ * API key credential), Scopes what to ask for (an OAuth one), Capabilities
+ * the platform-defined grants it needs ("x.tweet.read", "google.sheets":
+ * an OAuth grant with the scopes it implies), each a capability of the
+ * entry's own provider. Provider seeds the catalog row for the company the
+ * first time it is seen and never overwrites it; Auth seeds the auth scheme
+ * when the slug is free.
  * 	credentials:
- * 	  - provider: acme
- * 	    name: Acme CRM
- * 	    website: acme.com
+ * 	  slack:
+ * 	    capabilities: [slack.channels.write]
+ * 	  acme:
  * 	    secrets: [ACME_API_KEY]
- * Key is a capability of a provider the platform defines ("x.tweet.read",
- * "google.sheets"): an OAuth grant with the scopes it implies. An entry sets
- * Provider, Key, or both; with both, Key decides how it is resolved.
+ * 	    provider: {name: Acme CRM, website: acme.com}
+ * The list form that preceded it is still read: `- provider: acme` names
+ * the slug, `- key: x.tweet.read` a capability (its slug is the part
+ * before the first dot), `name:` and `website:` seed the provider.
  */
 export interface CredentialRequirement {
-    provider?: string;
-    /**
-     * Name and Website describe a provider the platform does not list: the
-     * name its credential is shown under and the site its logo comes from.
-     */
-    name?: string;
-    website?: string;
-    key?: string;
+    slug?: string;
+    capabilities?: string[];
     description?: string;
     optional?: boolean;
     secrets?: string[];
     scopes?: string[];
+    /**
+     * Provider describes the company the credential belongs to, for a
+     * catalog row that does not exist yet. Its slug defaults to the
+     * credential slug.
+     */
+    provider?: ProviderSeed;
+    /**
+     * Auth is the credential's auth scheme, for a slug no row defines yet.
+     */
+    auth?: AuthSchemeSpec;
+}
+/**
+ * ProviderSeed is a provider (the company behind a credential) as an app
+ * declares it: enough to create its catalog row when none exists.
+ */
+export interface ProviderSeed {
+    slug?: string;
+    name?: string;
+    description?: string;
+    website?: string;
+    logo_uri?: string;
+    docs_uri?: string;
+    tos_uri?: string;
+    policy_uri?: string;
+}
+/**
+ * CredentialRequirementWire is the entry as written, in either form: the
+ * current fields plus the list form's provider (a string there, the seed
+ * here), key, name and website. Exported, with everything it needs, so the
+ * generated copy of the type (the models module the CLI reads inf.yml with)
+ * carries the same parsing.
+ */
+export interface CredentialRequirementWire {
+    slug: string;
+    capabilities: string[];
+    description: string;
+    optional: boolean;
+    secrets: string[];
+    scopes: string[];
+    provider: any;
+    auth: any;
+    key: string;
+    name: string;
+    website: string;
 }
+/**
+ * CredentialRequirements is the credentials: list of a manifest. It reads
+ * both forms: a map keyed by credential slug (the current one) and a list
+ * of entries; it is always written as a list.
+ */
+export type CredentialRequirements = CredentialRequirement[];
 /**
  * ToolAnnotations describes tool behavior so clients can make trust and UX
  * decisions (e.g., auto-approve read-only tools). All fields are optional hints.
@@ -89,6 +139,372 @@ export interface OutputMeta {
     inputs: MetaItem[];
     outputs: MetaItem[];
 }
+/**
+ * AuthSchemeKind is how a provider authenticates: the kinds of an OpenAPI
+ * Security Scheme Object (oauth2, apiKey, http), named the same so a
+ * vendor's spec maps onto a scheme without translation.
+ */
+export type AuthSchemeKind = "oauth2" | "api_key" | "http" | "oauth2_authorization_code";
+/**
+ * AuthSchemeOAuth2 is OAuth 2.0; Flow says which grant.
+ */
+export declare const AuthSchemeOAuth2: AuthSchemeKind;
+/**
+ * AuthSchemeAPIKey is one or more keys a person pastes, sent as a
+ * header or query parameter.
+ */
+export declare const AuthSchemeAPIKey: AuthSchemeKind;
+/**
+ * AuthSchemeHTTP is a pasted secret sent as an HTTP auth scheme
+ * (Authorization: Bearer or Basic).
+ */
+export declare const AuthSchemeHTTP: AuthSchemeKind;
+/**
+ * Deprecated: the kind is AuthSchemeOAuth2 with AuthSchemeFlowAuthorizationCode.
+ * Same value, so comparisons keep working; rows still stored as
+ * "oauth2_authorization_code" are read as oauth2 (UnmarshalJSON).
+ */
+export declare const AuthSchemeOAuth2AuthorizationCode: "oauth2";
+/**
+ * AuthSchemeFlow is the OAuth 2.0 grant an oauth2 scheme uses.
+ */
+export type AuthSchemeFlow = "authorization_code" | "client_credentials";
+/**
+ * AuthSchemeFlowAuthorizationCode is the user-consent flow: authorization
+ * endpoint → code → token endpoint, optionally with PKCE. The default.
+ */
+export declare const AuthSchemeFlowAuthorizationCode: AuthSchemeFlow;
+/**
+ * AuthSchemeFlowClientCredentials is server-to-server: the app's client
+ * id and secret are exchanged at the token endpoint, no redirect, no
+ * user. The login is the app's own.
+ */
+export declare const AuthSchemeFlowClientCredentials: AuthSchemeFlow;
+/**
+ * AuthSchemeAPIKeyIn is where an api_key scheme's key travels.
+ */
+export type AuthSchemeAPIKeyIn = "header" | "query";
+export declare const AuthSchemeAPIKeyInHeader: AuthSchemeAPIKeyIn;
+export declare const AuthSchemeAPIKeyInQuery: AuthSchemeAPIKeyIn;
+/**
+ * AuthSchemeHTTPScheme is the Authorization scheme of an http scheme.
+ */
+export type AuthSchemeHTTPScheme = "bearer" | "basic";
+export declare const AuthSchemeHTTPBearer: AuthSchemeHTTPScheme;
+export declare const AuthSchemeHTTPBasic: AuthSchemeHTTPScheme;
+/**
+ * SecretField is one value a person pastes to connect an api_key or http
+ * scheme: its vault key and how the form asks for it. Several fields make
+ * a multi-secret provider (Kling's access and secret key).
+ */
+export interface SecretField {
+    key: string;
+    label?: string;
+    placeholder?: string;
+    sensitive?: boolean;
+    optional?: boolean;
+}
+/**
+ * AuthSchemeClientAuth is how client_id/client_secret reach the token
+ * endpoint. Most providers accept either; a few insist on one.
+ */
+export type AuthSchemeClientAuth = "basic" | "body";
+/**
+ * AuthSchemeClientAuthBasic sends them as an HTTP Basic Authorization
+ * header (RFC 6749 §2.3.1, the default).
+ */
+export declare const AuthSchemeClientAuthBasic: AuthSchemeClientAuth;
+/**
+ * AuthSchemeClientAuthBody sends them as form fields in the request body.
+ */
+export declare const AuthSchemeClientAuthBody: AuthSchemeClientAuth;
+/**
+ * AuthSchemeTokenRequest is the token request's body encoding.
+ */
+export type AuthSchemeTokenRequest = "form" | "json";
+export declare const AuthSchemeTokenRequestForm: AuthSchemeTokenRequest;
+export declare const AuthSchemeTokenRequestJSON: AuthSchemeTokenRequest;
+/**
+ * AuthSchemeRefresh is when an access token is refreshed.
+ */
+export type AuthSchemeRefresh = "" | "always";
+/**
+ * AuthSchemeRefreshWhenExpiring refreshes within five minutes of the
+ * reported expiry; a token with no expiry is treated as long-lived
+ * (Slack without token rotation, Notion).
+ */
+export declare const AuthSchemeRefreshWhenExpiring: AuthSchemeRefresh;
+/**
+ * AuthSchemeRefreshAlways refreshes on every read: the provider reports
+ * no expiry but the token does expire (Salesforce's session timeout is
+ * per org and not reported).
+ */
+export declare const AuthSchemeRefreshAlways: AuthSchemeRefresh;
+/**
+ * AuthSchemeRevokeStyle is how the token reaches the revoke endpoint.
+ */
+export type AuthSchemeRevokeStyle = "bearer" | "query" | "form";
+export declare const AuthSchemeRevokeBearer: AuthSchemeRevokeStyle;
+export declare const AuthSchemeRevokeQuery: AuthSchemeRevokeStyle;
+export declare const AuthSchemeRevokeForm: AuthSchemeRevokeStyle;
+/**
+ * AuthSchemeRevoke is the optional token revocation on disconnect.
+ */
+export interface AuthSchemeRevoke {
+    url: string;
+    style: AuthSchemeRevokeStyle;
+    /**
+     * ClientAuth also sends client_id and client_secret in the form
+     * (Discord).
+     */
+    client_auth?: boolean;
+}
+/**
+ * AuthSchemeAppKey is one key of the OAuth app a login goes through. The
+ * client id and secret are implied (PREFIX_CLIENT_ID, PREFIX_CLIENT_SECRET);
+ * listing them only overrides their label and placeholder. Other keys
+ * (bot_token, signing_secret, tenant_id) are optional extras the app holds,
+ * read back by name in templates as {app.<name>} and by hooks.
+ */
+export interface AuthSchemeAppKey {
+    /**
+     * Name is the key's role: client_id, client_secret, bot_token, …
+     */
+    name: string;
+    /**
+     * Key is the vault key; default PREFIX_<NAME>.
+     */
+    key?: string;
+    label?: string;
+    placeholder?: string;
+    sensitive?: boolean;
+    /**
+     * Optional is implied for every name but client_id and client_secret.
+     */
+    optional?: boolean;
+}
+/**
+ * AuthSchemeLookup is a call made after the token exchange, with the new
+ * access token as bearer; its decoded response becomes a document root of
+ * its name for the identity, metadata and later lookups ({user.email},
+ * {resources.0.id}). userinfo_url is shorthand for the lookup named user.
+ * URL, body and headers are templates.
+ */
+export interface AuthSchemeLookup {
+    name: string;
+    url: string;
+    method?: string;
+    /**
+     * Body is sent as is; a JSON body is the default content type
+     * (Dropbox's "null", Linear's GraphQL query).
+     */
+    body?: string;
+    content_type?: string;
+    headers?: {
+        [key: string]: string;
+    };
+}
+/**
+ * AuthSchemeCapability is something an app can ask for from this provider,
+ * satisfied by a connection holding its scopes. Scopes are in the scheme's
+ * own (friendly) names, the ones a credential stores.
+ */
+export interface AuthSchemeCapability {
+    key: string;
+    scopes?: string[];
+    satisfies?: string[];
+    display_name: string;
+    description?: string;
+}
+/**
+ * AuthSchemeSpec is one way to authenticate against a provider, as data.
+ * Everything a standard OAuth2 provider needs is a field; where a provider
+ * deviates in a way data cannot express, the spec names a hook and Go
+ * supplies it (authprovider.RegisterTokenResponseHook and friends).
+ * Templates: URLs, headers, lookup bodies, identifier, name, metadata and
+ * env values are strings with {{path}} placeholders. A path is read from
+ * the flow's document, which grows as the flow goes:
+ * 	client_id                  from the authorize step on
+ * 	vars.* (and each var bare)  what the vars hook produced, e.g. {{tenant}}
+ * 	access_token, token.*      after the token exchange (token.* is the
+ * 	                           decoded response)
+ * 	callback.*                 the other query params the callback carried
+ * 	                           (QuickBooks' realmId, Shopify's shop)
+ * 	<lookup>.*                 each lookup's response, by its name; user.*
+ * 	                           is the userinfo lookup
+ * 	expires_at, metadata.*, app.*   env only: the token's expiry (RFC 3339),
+ * 	                           the stored metadata, the app's extra keys
+ * Array elements are indexed: {{resources.0.id}}. {{a|b}} takes the first
+ * path present. A template none of whose placeholders resolve renders "":
+ * omitted from env and metadata, blank as identifier or name.
+ */
+export interface AuthSchemeSpec {
+    kind: AuthSchemeKind;
+    /**
+     * Flow is the oauth2 grant; empty means authorization_code.
+     */
+    flow?: AuthSchemeFlow;
+    /**
+     * Fields are what a person pastes (api_key and http kinds).
+     */
+    fields?: SecretField[];
+    /**
+     * In and ParamName say where an api_key key goes on a request: the
+     * header or query parameter of that name. ValuePrefix is prepended to
+     * the value ("Bearer "). Not needed to connect; read by injection.
+     */
+    in?: AuthSchemeAPIKeyIn;
+    param_name?: string;
+    value_prefix?: string;
+    /**
+     * Scheme and BearerFormat describe an http kind's Authorization header.
+     */
+    scheme?: AuthSchemeHTTPScheme;
+    bearer_format?: string;
+    authorization_endpoint?: string;
+    scopes?: string[];
+    /**
+     * ScopeAliases map the scheme's own scope names to what the provider
+     * wants on the wire ("gmail.send" → "https://www.googleapis.com/auth/
+     * gmail.send"). Credentials store the alias; the wire form is used only
+     * in requests. A scope with no alias is sent as is.
+     */
+    scope_aliases?: {
+        [key: string]: string;
+    };
+    scope_param?: string;
+    scope_separator?: string;
+    omit_scope_param?: boolean;
+    pkce?: boolean;
+    /**
+     * ClientIDParam is the name the client id travels under in the
+     * authorize URL and the token body; default "client_id" (TikTok:
+     * "client_key").
+     */
+    client_id_param?: string;
+    /**
+     * ExtraAuthorizeParams are appended to the authorize URL verbatim
+     * (Google's access_type=offline). AddScopesParams override them when
+     * re-authorizing for more scopes (Google's include_granted_scopes).
+     */
+    extra_authorize_params?: {
+        [key: string]: string;
+    };
+    add_scopes_params?: {
+        [key: string]: string;
+    };
+    /**
+     * AccountHintParam is the authorize param that names the account to sign
+     * in with (Google's and Microsoft's "login_hint"). When re-authorizing
+     * for more scopes it carries the login's account identifier, so the
+     * provider goes to that account instead of offering a chooser. Empty =
+     * no hint sent.
+     */
+    account_hint_param?: string;
+    /**
+     * AnotherAccountParams are authorize params for connecting an account
+     * next to one already connected: the provider shows its account chooser
+     * instead of signing the user back in to the account it remembers
+     * (Google prompt=select_account). They override ExtraAuthorizeParams.
+     */
+    another_account_params?: {
+        [key: string]: string;
+    };
+    /**
+     * RequiredScopes are always requested, on a connect and when
+     * re-authorizing for more scopes, whatever the caller asked for: the
+     * scopes the identity lookup and token refresh need (Google's openid,
+     * email and profile; X's users.read and offline.access). In the
+     * scheme's own names, like Scopes. Empty = only what was asked for.
+     */
+    required_scopes?: string[];
+    /**
+     * IncrementalAddScopes: re-authorizing for more scopes asks only for
+     * the new ones (plus RequiredScopes), and the provider returns a token
+     * that also covers what the login already holds (Google, with
+     * include_granted_scopes in AddScopesParams). Without it the full list
+     * is asked for again.
+     */
+    incremental_add_scopes?: boolean;
+    token_endpoint?: string;
+    /**
+     * RevocationEndpoint is the RFC 7009 endpoint, when the provider has
+     * one and Revoke names no style of its own: tokens are revoked there
+     * with a form POST.
+     */
+    revocation_endpoint?: string;
+    client_auth?: AuthSchemeClientAuth;
+    token_request?: AuthSchemeTokenRequest;
+    /**
+     * Headers go on every request to the provider (User-Agent for Reddit,
+     * Notion-Version); values are templates ({{client_id}} for Twitch's
+     * Client-Id).
+     */
+    headers?: {
+        [key: string]: string;
+    };
+    /**
+     * TokenResponseHook names the Go reader for a token response that is
+     * not the RFC 6749 shape (Slack's nested authed_user). Empty = standard.
+     */
+    token_response_hook?: string;
+    refresh?: AuthSchemeRefresh;
+    revoke?: AuthSchemeRevoke;
+    /**
+     * UserInfoURL is fetched with the new access token; the response is the
+     * identity document (user.*). UserInfoURLPath instead reads that URL
+     * from a path within the token response (Salesforce's "id"). Lookups
+     * are further calls, each becoming a root of its name, in order, after
+     * user. With none of these, the token response is all there is.
+     */
+    userinfo_url?: string;
+    userinfo_url_path?: string;
+    lookups?: AuthSchemeLookup[];
+    /**
+     * Identifier is the connected account's stable, human-readable id
+     * ("{{user.email}}", "@{{user.data.username}}"); Name its display name.
+     */
+    identifier?: string;
+    name?: string;
+    /**
+     * AccountID is the account's id as the provider keeps it and never
+     * changes it ("{{user.sub}}" for Google, "{{user.data.id}}" for X), as
+     * opposed to Identifier, which the user may rename. Logins are matched
+     * and chosen by it. Empty = Identifier, for providers whose identifier
+     * already is such an id (Slack, Notion).
+     */
+    account_id?: string;
+    /**
+     * IdentityHook names Go code that derives identifier and name when a
+     * template cannot (Discord's discriminator rule). It wins over both.
+     */
+    identity_hook?: string;
+    /**
+     * Metadata is what the credential stores about the account, by key.
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * Env is what a run reads, by variable. Empty = PREFIX_ACCESS_TOKEN and
+     * PREFIX_ACCESS_TOKEN_EXPIRES_AT.
+     */
+    env?: {
+        [key: string]: string;
+    };
+    /**
+     * AppKeys are the OAuth app's keys beyond the implied client id and
+     * secret, and label overrides for those.
+     */
+    app_keys?: AuthSchemeAppKey[];
+    /**
+     * VarsHook names Go code that turns the app's extra keys into the
+     * {var} values substituted into the URLs (Microsoft's tenant,
+     * Salesforce's sandbox host).
+     */
+    vars_hook?: string;
+    capabilities?: AuthSchemeCapability[];
+}
 /**
  * MetaItemType is the type discriminator for MetaItem
  */

package/dist/types.js

@@ -1,4 +1,65 @@
 // Code generated by gotypegen. DO NOT EDIT.
+/**
+ * AuthSchemeOAuth2 is OAuth 2.0; Flow says which grant.
+ */
+export const AuthSchemeOAuth2 = "oauth2";
+/**
+ * AuthSchemeAPIKey is one or more keys a person pastes, sent as a
+ * header or query parameter.
+ */
+export const AuthSchemeAPIKey = "api_key";
+/**
+ * AuthSchemeHTTP is a pasted secret sent as an HTTP auth scheme
+ * (Authorization: Bearer or Basic).
+ */
+export const AuthSchemeHTTP = "http";
+/**
+ * Deprecated: the kind is AuthSchemeOAuth2 with AuthSchemeFlowAuthorizationCode.
+ * Same value, so comparisons keep working; rows still stored as
+ * "oauth2_authorization_code" are read as oauth2 (UnmarshalJSON).
+ */
+export const AuthSchemeOAuth2AuthorizationCode = AuthSchemeOAuth2;
+/**
+ * AuthSchemeFlowAuthorizationCode is the user-consent flow: authorization
+ * endpoint → code → token endpoint, optionally with PKCE. The default.
+ */
+export const AuthSchemeFlowAuthorizationCode = "authorization_code";
+/**
+ * AuthSchemeFlowClientCredentials is server-to-server: the app's client
+ * id and secret are exchanged at the token endpoint, no redirect, no
+ * user. The login is the app's own.
+ */
+export const AuthSchemeFlowClientCredentials = "client_credentials";
+export const AuthSchemeAPIKeyInHeader = "header";
+export const AuthSchemeAPIKeyInQuery = "query";
+export const AuthSchemeHTTPBearer = "bearer";
+export const AuthSchemeHTTPBasic = "basic";
+/**
+ * AuthSchemeClientAuthBasic sends them as an HTTP Basic Authorization
+ * header (RFC 6749 §2.3.1, the default).
+ */
+export const AuthSchemeClientAuthBasic = "basic";
+/**
+ * AuthSchemeClientAuthBody sends them as form fields in the request body.
+ */
+export const AuthSchemeClientAuthBody = "body";
+export const AuthSchemeTokenRequestForm = "form";
+export const AuthSchemeTokenRequestJSON = "json";
+/**
+ * AuthSchemeRefreshWhenExpiring refreshes within five minutes of the
+ * reported expiry; a token with no expiry is treated as long-lived
+ * (Slack without token rotation, Notion).
+ */
+export const AuthSchemeRefreshWhenExpiring = "";
+/**
+ * AuthSchemeRefreshAlways refreshes on every read: the provider reports
+ * no expiry but the token does expire (Salesforce's session timeout is
+ * per org and not reported).
+ */
+export const AuthSchemeRefreshAlways = "always";
+export const AuthSchemeRevokeBearer = "bearer";
+export const AuthSchemeRevokeQuery = "query";
+export const AuthSchemeRevokeForm = "form";
 export const MetaItemTypeText = "text";
 export const MetaItemTypeImage = "image";
 export const MetaItemTypeVideo = "video";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/app",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
   "type": "module",
   "main": "dist/index.js",