@formfeed/sdk 0.3.2 → 0.3.4

package/index.cjs

@@ -78,6 +78,7 @@ var Formfeed = class {
   fetchImpl;
   maxRetries;
   timeoutMs;
+  extraHeaders;
   constructor(options) {
     if (!options.apiKey) throw new FormfeedError("invalid_request", "apiKey is required", 0);
     this.apiKey = options.apiKey;
@@ -85,6 +86,7 @@ var Formfeed = class {
     this.fetchImpl = options.fetch ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? 3;
     this.timeoutMs = options.timeoutMs ?? 12e4;
+    this.extraHeaders = Object.fromEntries(Object.entries(options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
     if (!this.fetchImpl) throw new FormfeedError("invalid_request", "fetch is not available; pass options.fetch", 0);
   }
   renders = {
@@ -352,11 +354,20 @@ var Formfeed = class {
         );
       }
     },
-    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
+    /**
+     * The JSON Schema of the template's data: stored, else inferred from the sample data. Of the
+     * published (else the latest) version, or of `version`: `published`, `latest`, a number or a
+     * channel name.
+     */
+    schema: (idOrSlug, options = {}) => {
+      const { version, ...rest } = options;
+      const query = version === void 0 ? "" : `?version=${encodeURIComponent(String(version))}`;
+      return this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema${query}`, void 0, rest);
+    },
     /**
      * Checks a version with data without rendering: syntax, header and footer, missing partials,
      * runtime errors and the data against the stored schema. Free. Without `data`, the version's
-     * sample data is checked.
+     * sample data is checked. `version` takes a channel name too.
      */
     validate: (idOrSlug, input = {}, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/validate`, input, options)
   };
@@ -395,7 +406,8 @@ var Formfeed = class {
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
       accept: as === "bytes" ? "*/*" : "application/json",
-      "user-agent": "formfeed-sdk-ts/0.3"
+      "user-agent": "formfeed-sdk-ts/0.3",
+      ...this.extraHeaders
     };
     const isForm = typeof FormData !== "undefined" && body instanceof FormData;
     if (body !== void 0 && !isForm) headers["content-type"] = "application/json";

package/index.js

@@ -49,6 +49,7 @@ var Formfeed = class {
   fetchImpl;
   maxRetries;
   timeoutMs;
+  extraHeaders;
   constructor(options) {
     if (!options.apiKey) throw new FormfeedError("invalid_request", "apiKey is required", 0);
     this.apiKey = options.apiKey;
@@ -56,6 +57,7 @@ var Formfeed = class {
     this.fetchImpl = options.fetch ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? 3;
     this.timeoutMs = options.timeoutMs ?? 12e4;
+    this.extraHeaders = Object.fromEntries(Object.entries(options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
     if (!this.fetchImpl) throw new FormfeedError("invalid_request", "fetch is not available; pass options.fetch", 0);
   }
   renders = {
@@ -323,11 +325,20 @@ var Formfeed = class {
         );
       }
     },
-    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
+    /**
+     * The JSON Schema of the template's data: stored, else inferred from the sample data. Of the
+     * published (else the latest) version, or of `version`: `published`, `latest`, a number or a
+     * channel name.
+     */
+    schema: (idOrSlug, options = {}) => {
+      const { version, ...rest } = options;
+      const query = version === void 0 ? "" : `?version=${encodeURIComponent(String(version))}`;
+      return this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema${query}`, void 0, rest);
+    },
     /**
      * Checks a version with data without rendering: syntax, header and footer, missing partials,
      * runtime errors and the data against the stored schema. Free. Without `data`, the version's
-     * sample data is checked.
+     * sample data is checked. `version` takes a channel name too.
      */
     validate: (idOrSlug, input = {}, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/validate`, input, options)
   };
@@ -366,7 +377,8 @@ var Formfeed = class {
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
       accept: as === "bytes" ? "*/*" : "application/json",
-      "user-agent": "formfeed-sdk-ts/0.3"
+      "user-agent": "formfeed-sdk-ts/0.3",
+      ...this.extraHeaders
     };
     const isForm = typeof FormData !== "undefined" && body instanceof FormData;
     if (body !== void 0 && !isForm) headers["content-type"] = "application/json";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/sdk",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Formfeed API client: renders, templates, webhooks. No dependencies, Web APIs only.",
   "license": "MIT",
   "type": "module",

package/types/index.d.cts

@@ -1,4 +1,4 @@
 export { Formfeed, FormfeedError } from './lib/client.cjs';
-export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, TemplateVersion, TemplateVersionCreate, TemplateFile, OfficeTemplateKind, OfficeTemplateCreate, OfficeVersionCreate, OfficeFileUpload, ConvertOptions, VersionStatus, BatchRequest, Channel, ChannelList, ChannelMove, Brand, SharedPartial, SharedPartialPut, SharedPartialPutResult, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, FormfeedTemplates, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, TemplateData, TypedRenderRequest, RequestOptions, SchemaChange, SchemaCheck, SchemaGuardOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, WebhookEndpointCreate, WebhookEndpointUpdate, WebhookEnvironment, WebhookResend, ListenSession, ListenSessionOptions, RenderInput, } from './lib/client.cjs';
+export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, VersionRef, TemplateVersion, TemplateVersionCreate, TemplateFile, OfficeTemplateKind, OfficeTemplateCreate, OfficeVersionCreate, OfficeFileUpload, ConvertOptions, VersionStatus, BatchRequest, Channel, ChannelList, ChannelMove, Brand, SharedPartial, SharedPartialPut, SharedPartialPutResult, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, FormfeedTemplates, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, TemplateData, TypedRenderRequest, RequestOptions, SchemaChange, SchemaCheck, SchemaGuardOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, WebhookEndpointCreate, WebhookEndpointUpdate, WebhookEnvironment, WebhookResend, ListenSession, ListenSessionOptions, RenderInput, } from './lib/client.cjs';
 export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.cjs';
 export type { VerifyOptions } from './lib/webhooks.cjs';

package/types/index.d.ts

@@ -1,4 +1,4 @@
 export { Formfeed, FormfeedError } from './lib/client.js';
-export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, TemplateVersion, TemplateVersionCreate, TemplateFile, OfficeTemplateKind, OfficeTemplateCreate, OfficeVersionCreate, OfficeFileUpload, ConvertOptions, VersionStatus, BatchRequest, Channel, ChannelList, ChannelMove, Brand, SharedPartial, SharedPartialPut, SharedPartialPutResult, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, FormfeedTemplates, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, TemplateData, TypedRenderRequest, RequestOptions, SchemaChange, SchemaCheck, SchemaGuardOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, WebhookEndpointCreate, WebhookEndpointUpdate, WebhookEnvironment, WebhookResend, ListenSession, ListenSessionOptions, RenderInput, } from './lib/client.js';
+export type { Template, TemplateCreate, TemplateFiles, TemplateKind, TemplateListOptions, TemplateValidation, VersionRef, TemplateVersion, TemplateVersionCreate, TemplateFile, OfficeTemplateKind, OfficeTemplateCreate, OfficeVersionCreate, OfficeFileUpload, ConvertOptions, VersionStatus, BatchRequest, Channel, ChannelList, ChannelMove, Brand, SharedPartial, SharedPartialPut, SharedPartialPutResult, Diagnostic, Engine, FileListOptions, FileUpload, FormfeedOptions, FormfeedTemplates, Job, LibraryFile, OutputFormat, PdfInfo, PdfOutputOptions, PdfPermission, PostProcessing, Problem, ProtectOptions, Region, Render, RenderListOptions, RenderRequest, RenderStatus, TemplateData, TypedRenderRequest, RequestOptions, SchemaChange, SchemaCheck, SchemaGuardOptions, Usage, WaitOptions, WatermarkOptions, WebhookEndpoint, WebhookEndpointCreate, WebhookEndpointUpdate, WebhookEnvironment, WebhookResend, ListenSession, ListenSessionOptions, RenderInput, } from './lib/client.js';
 export { parseWebhookEvent, verifyWebhookSignature } from './lib/webhooks.js';
 export type { VerifyOptions } from './lib/webhooks.js';

package/types/lib/client.d.cts

@@ -22,6 +22,12 @@ export interface FormfeedOptions {
     /** Retries on 429 and 503; 0 disables. */
     maxRetries?: number;
     timeoutMs?: number;
+    /**
+     * Headers sent with every request, after the SDK's own. The hosted MCP server uses it to act for
+     * a signed-in member: `apiKey` carries the OAuth access token and `X-Formfeed-Workspace` the
+     * workspace of the URL (spec 10 §3.1).
+     */
+    headers?: Record<string, string>;
 }
 export interface RenderRequest {
     template?: string;
@@ -391,6 +397,8 @@ export interface Template {
     created_at: string;
     updated_at: string;
 }
+/** A version as reads name it: `published`, `latest`, a version number or a channel name (its main version). */
+export type VersionRef = string | number;
 /** One finding of `templates.validate`. */
 export interface Diagnostic {
     severity: 'error' | 'warning' | 'info';
@@ -402,6 +410,10 @@ export interface Diagnostic {
     };
     /** Data errors only: where in the data, e.g. `data.invoice.lines[0].qty`. */
     path?: string;
+    /** Word and PowerPoint templates only: the file part the tag is in, e.g. `word/document.xml`. */
+    part?: string;
+    /** Word and PowerPoint templates only: the 1-based paragraph in `part`. */
+    paragraph?: number;
 }
 export interface TemplateValidation {
     /** `false` when at least one diagnostic is an error. */
@@ -606,6 +618,7 @@ export declare class Formfeed {
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly timeoutMs;
+    private readonly extraHeaders;
     constructor(options: FormfeedOptions);
     readonly renders: {
         /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
@@ -762,14 +775,21 @@ export declare class Formfeed {
                 force?: boolean;
             }) => Promise<void>;
         };
-        schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /**
+         * The JSON Schema of the template's data: stored, else inferred from the sample data. Of the
+         * published (else the latest) version, or of `version`: `published`, `latest`, a number or a
+         * channel name.
+         */
+        schema: (idOrSlug: string, options?: RequestOptions & {
+            version?: VersionRef;
+        }) => Promise<Record<string, unknown>>;
         /**
          * Checks a version with data without rendering: syntax, header and footer, missing partials,
          * runtime errors and the data against the stored schema. Free. Without `data`, the version's
-         * sample data is checked.
+         * sample data is checked. `version` takes a channel name too.
          */
         validate: (idOrSlug: string, input?: {
-            version?: "published" | "latest" | number;
+            version?: VersionRef;
             data?: Record<string, unknown>;
         }, options?: RequestOptions) => Promise<TemplateValidation>;
     };

package/types/lib/client.d.ts

@@ -22,6 +22,12 @@ export interface FormfeedOptions {
     /** Retries on 429 and 503; 0 disables. */
     maxRetries?: number;
     timeoutMs?: number;
+    /**
+     * Headers sent with every request, after the SDK's own. The hosted MCP server uses it to act for
+     * a signed-in member: `apiKey` carries the OAuth access token and `X-Formfeed-Workspace` the
+     * workspace of the URL (spec 10 §3.1).
+     */
+    headers?: Record<string, string>;
 }
 export interface RenderRequest {
     template?: string;
@@ -391,6 +397,8 @@ export interface Template {
     created_at: string;
     updated_at: string;
 }
+/** A version as reads name it: `published`, `latest`, a version number or a channel name (its main version). */
+export type VersionRef = string | number;
 /** One finding of `templates.validate`. */
 export interface Diagnostic {
     severity: 'error' | 'warning' | 'info';
@@ -402,6 +410,10 @@ export interface Diagnostic {
     };
     /** Data errors only: where in the data, e.g. `data.invoice.lines[0].qty`. */
     path?: string;
+    /** Word and PowerPoint templates only: the file part the tag is in, e.g. `word/document.xml`. */
+    part?: string;
+    /** Word and PowerPoint templates only: the 1-based paragraph in `part`. */
+    paragraph?: number;
 }
 export interface TemplateValidation {
     /** `false` when at least one diagnostic is an error. */
@@ -606,6 +618,7 @@ export declare class Formfeed {
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly timeoutMs;
+    private readonly extraHeaders;
     constructor(options: FormfeedOptions);
     readonly renders: {
         /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
@@ -762,14 +775,21 @@ export declare class Formfeed {
                 force?: boolean;
             }) => Promise<void>;
         };
-        schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /**
+         * The JSON Schema of the template's data: stored, else inferred from the sample data. Of the
+         * published (else the latest) version, or of `version`: `published`, `latest`, a number or a
+         * channel name.
+         */
+        schema: (idOrSlug: string, options?: RequestOptions & {
+            version?: VersionRef;
+        }) => Promise<Record<string, unknown>>;
         /**
          * Checks a version with data without rendering: syntax, header and footer, missing partials,
          * runtime errors and the data against the stored schema. Free. Without `data`, the version's
-         * sample data is checked.
+         * sample data is checked. `version` takes a channel name too.
          */
         validate: (idOrSlug: string, input?: {
-            version?: "published" | "latest" | number;
+            version?: VersionRef;
             data?: Record<string, unknown>;
         }, options?: RequestOptions) => Promise<TemplateValidation>;
     };