@scalar/api-client 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @scalar/api-client
 
+## 3.2.0
+
+### Minor Changes
+
+- [#8891](https://github.com/scalar/scalar/pull/8891): feat: support refreshing the token
+
+### Patch Changes
+
+- [#8877](https://github.com/scalar/scalar/pull/8877): fix(api-client): prefill oauth2 redirect URI after switching documents
+- [#8943](https://github.com/scalar/scalar/pull/8943): feat: added customFetch config to the client
+- [#8931](https://github.com/scalar/scalar/pull/8931): fix: close environment selector dropdown after selection
+- [#8933](https://github.com/scalar/scalar/pull/8933): feat(api-client): add app-level oauth2 redirect URI override plumbing for auth prefill
+- [#8932](https://github.com/scalar/scalar/pull/8932): fix: only enable fake data suggestion for parameteres and request body
+- [#8907](https://github.com/scalar/scalar/pull/8907): Fix code sample missing body content type update
+
+## 3.1.0
+
+### Minor Changes
+
+- [#8865](https://github.com/scalar/scalar/pull/8865): feat: add plugin support for custom response body content types
+
+### Patch Changes
+
+- [#8810](https://github.com/scalar/scalar/pull/8810): refactor: move telemetry to an optional plugin
+- [#8912](https://github.com/scalar/scalar/pull/8912): fix: provide a default summary when creating a new temp operation
+- [#8903](https://github.com/scalar/scalar/pull/8903): fix: share Postman collection detection from postman-to-openapi
+- [#8911](https://github.com/scalar/scalar/pull/8911): feat: switch from Request to RequestPayload to support body with GET
+- [#8887](https://github.com/scalar/scalar/pull/8887): fix: invalid json body handling and add root document for bulk operation selection
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -165,6 +165,47 @@ The `createApiClientModal` call returns:
 ```
 
 
+## Plugins
+
+The `plugins` option accepts an array of `ClientPlugin` objects that extend the API Client with custom behavior. Plugins can add lifecycle hooks, custom UI components, and custom response body handlers for content types that the client does not natively support.
+
+### Custom Response Body Handling
+
+When your API returns a non-standard content type (for example, MessagePack), you can register a plugin with a `responseBody` handler to decode and display it:
+
+```ts
+import type { ClientPlugin } from '@scalar/oas-utils/helpers'
+
+const msgpackPlugin: ClientPlugin = {
+  responseBody: [
+    {
+      mimeTypes: ['application/msgpack', 'application/x-msgpack'],
+      decode: async (buffer) => {
+        const { decode } = await import('@msgpack/msgpack')
+        const decoded = decode(new Uint8Array(buffer))
+        return JSON.stringify(decoded, null, 2)
+      },
+      language: 'json',
+    },
+  ],
+}
+
+createApiClientApp(el, {
+  layout: 'web',
+  plugins: [msgpackPlugin],
+})
+```
+
+Each handler in `responseBody` supports:
+
+| Property | Description |
+|---|---|
+| `mimeTypes` | MIME type patterns to match (exact or wildcard like `application/vnd.*+json`). |
+| `decode` | Transforms the raw `ArrayBuffer` into a string or Blob for display. |
+| `language` | CodeMirror language hint for the built-in raw renderer (for example, `json`). |
+| `rawComponent` | A custom Vue component for the raw view (mutually exclusive with `language`). |
+| `previewComponent` | A custom Vue component for the preview view. |
+
 ## Community
 
 We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>

package/dist/components/HttpMethod/HttpMethod.vue.d.ts

@@ -4,9 +4,9 @@ type __VLS_Props = {
     isEditable?: boolean;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
-    change: (value: "delete" | "head" | "get" | "options" | "put" | "post" | "patch" | "trace") => any;
+    change: (value: "head" | "delete" | "get" | "options" | "patch" | "post" | "put" | "trace") => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onChange?: ((value: "delete" | "head" | "get" | "options" | "put" | "post" | "patch" | "trace") => any) | undefined;
+    onChange?: ((value: "head" | "delete" | "get" | "options" | "patch" | "post" | "put" | "trace") => any) | undefined;
 }>, {
     isSquare: boolean;
     isEditable: boolean;

package/dist/components/Sidebar/Actions/SidebarListElementForm.vue.d.ts

@@ -7,11 +7,11 @@ type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
-    submit: () => any;
     cancel: () => any;
+    submit: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onSubmit?: (() => any) | undefined;
     onCancel?: (() => any) | undefined;
+    onSubmit?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/plugins/posthog/index.d.ts

@@ -0,0 +1,23 @@
+import type { ClientPlugin } from '@scalar/oas-utils/helpers';
+import type { ConfigDefaults } from 'posthog-js';
+export type PostHogConfig = {
+    /** Your PostHog project API key */
+    apiKey: string;
+    /** The PostHog API host URL */
+    apiHost: string;
+    /** The PostHog UI host URL (for session recordings, surveys, etc.) */
+    uiHost?: string;
+    /** PostHog defaults version identifier */
+    defaults?: ConfigDefaults;
+};
+/**
+ * PostHog analytics plugin for the API Client.
+ *
+ * Loading this plugin opts in to analytics. If the plugin is not loaded,
+ * no tracking occurs.
+ *
+ * Respects the `telemetry` configuration option — when set to `false`,
+ * capturing is disabled. Reacts dynamically to config changes at runtime.
+ */
+export declare const PostHogClientPlugin: (config: PostHogConfig) => ClientPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/posthog/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/posthog/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,YAAY,CAAA;AAGzD,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,KAAG,YA4D3D,CAAA"}

package/dist/plugins/posthog/index.js

@@ -0,0 +1,58 @@
+import ph from "posthog-js";
+//#region src/plugins/posthog/index.ts
+/**
+* PostHog analytics plugin for the API Client.
+*
+* Loading this plugin opts in to analytics. If the plugin is not loaded,
+* no tracking occurs.
+*
+* Respects the `telemetry` configuration option — when set to `false`,
+* capturing is disabled. Reacts dynamically to config changes at runtime.
+*/
+var PostHogClientPlugin = (config) => {
+	let posthog = null;
+	return {
+		on: {
+			"hooks:on:request:sent": () => posthog?.capture("hooks:on:request:sent"),
+			"operation:create:operation": () => posthog?.capture("operation:create:operation"),
+			"operation:delete:operation": () => posthog?.capture("operation:delete:operation"),
+			"document:create:empty-document": () => posthog?.capture("document:create:empty-document"),
+			"document:delete:document": () => posthog?.capture("document:delete:document"),
+			"tag:create:tag": () => posthog?.capture("tag:create:tag"),
+			"server:add:server": () => posthog?.capture("server:add:server"),
+			"auth:update:selected-security-schemes": () => posthog?.capture("auth:update:selected-security-schemes"),
+			"environment:upsert:environment": () => posthog?.capture("environment:upsert:environment"),
+			"ui:open:client-modal": () => posthog?.capture("ui:open:client-modal"),
+			"ui:download:document": () => posthog?.capture("ui:download:document")
+		},
+		lifecycle: {
+			onInit(context) {
+				if (typeof window === "undefined") return;
+				const instance = ph.init(config.apiKey, {
+					api_host: config.apiHost,
+					...config.uiHost ? { ui_host: config.uiHost } : {},
+					...config.defaults ? { defaults: config.defaults } : {},
+					opt_out_capturing_by_default: true
+				}, "scalar-api-client");
+				if (instance) {
+					posthog = instance;
+					posthog.register({ product: "api-client" });
+					if (context?.config.telemetry !== false) posthog.opt_in_capturing();
+				}
+			},
+			onConfigChange(context) {
+				if (!posthog) return;
+				if (context.config.telemetry === false) posthog.opt_out_capturing();
+				else posthog.opt_in_capturing();
+			},
+			onDestroy() {
+				posthog?.reset();
+				posthog = null;
+			}
+		}
+	};
+};
+//#endregion
+export { PostHogClientPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist/plugins/posthog/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/plugins/posthog/index.ts"],"sourcesContent":["import type { ClientPlugin } from '@scalar/oas-utils/helpers'\nimport type { ConfigDefaults, PostHog } from 'posthog-js'\nimport ph from 'posthog-js'\n\nexport type PostHogConfig = {\n  /** Your PostHog project API key */\n  apiKey: string\n  /** The PostHog API host URL */\n  apiHost: string\n  /** The PostHog UI host URL (for session recordings, surveys, etc.) */\n  uiHost?: string\n  /** PostHog defaults version identifier */\n  defaults?: ConfigDefaults\n}\n\n/**\n * PostHog analytics plugin for the API Client.\n *\n * Loading this plugin opts in to analytics. If the plugin is not loaded,\n * no tracking occurs.\n *\n * Respects the `telemetry` configuration option — when set to `false`,\n * capturing is disabled. Reacts dynamically to config changes at runtime.\n */\nexport const PostHogClientPlugin = (config: PostHogConfig): ClientPlugin => {\n  let posthog: PostHog | null = null\n\n  return {\n    on: {\n      'hooks:on:request:sent': () => posthog?.capture('hooks:on:request:sent'),\n      'operation:create:operation': () => posthog?.capture('operation:create:operation'),\n      'operation:delete:operation': () => posthog?.capture('operation:delete:operation'),\n      'document:create:empty-document': () => posthog?.capture('document:create:empty-document'),\n      'document:delete:document': () => posthog?.capture('document:delete:document'),\n      'tag:create:tag': () => posthog?.capture('tag:create:tag'),\n      'server:add:server': () => posthog?.capture('server:add:server'),\n      'auth:update:selected-security-schemes': () => posthog?.capture('auth:update:selected-security-schemes'),\n      'environment:upsert:environment': () => posthog?.capture('environment:upsert:environment'),\n      'ui:open:client-modal': () => posthog?.capture('ui:open:client-modal'),\n      'ui:download:document': () => posthog?.capture('ui:download:document'),\n    },\n    lifecycle: {\n      onInit(context) {\n        if (typeof window === 'undefined') {\n          return\n        }\n\n        const instance = ph.init(\n          config.apiKey,\n          {\n            api_host: config.apiHost,\n            ...(config.uiHost ? { ui_host: config.uiHost } : {}),\n            ...(config.defaults ? { defaults: config.defaults } : {}),\n            opt_out_capturing_by_default: true,\n          },\n          'scalar-api-client',\n        )\n\n        if (instance) {\n          posthog = instance\n          posthog.register({ product: 'api-client' })\n\n          if (context?.config.telemetry !== false) {\n            posthog.opt_in_capturing()\n          }\n        }\n      },\n      onConfigChange(context) {\n        if (!posthog) {\n          return\n        }\n\n        if (context.config.telemetry === false) {\n          posthog.opt_out_capturing()\n        } else {\n          posthog.opt_in_capturing()\n        }\n      },\n      onDestroy() {\n        posthog?.reset()\n        posthog = null\n      },\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;AAwBA,IAAa,uBAAuB,WAAwC;CAC1E,IAAI,UAA0B;AAE9B,QAAO;EACL,IAAI;GACF,+BAA+B,SAAS,QAAQ,wBAAwB;GACxE,oCAAoC,SAAS,QAAQ,6BAA6B;GAClF,oCAAoC,SAAS,QAAQ,6BAA6B;GAClF,wCAAwC,SAAS,QAAQ,iCAAiC;GAC1F,kCAAkC,SAAS,QAAQ,2BAA2B;GAC9E,wBAAwB,SAAS,QAAQ,iBAAiB;GAC1D,2BAA2B,SAAS,QAAQ,oBAAoB;GAChE,+CAA+C,SAAS,QAAQ,wCAAwC;GACxG,wCAAwC,SAAS,QAAQ,iCAAiC;GAC1F,8BAA8B,SAAS,QAAQ,uBAAuB;GACtE,8BAA8B,SAAS,QAAQ,uBAAuB;GACvE;EACD,WAAW;GACT,OAAO,SAAS;AACd,QAAI,OAAO,WAAW,YACpB;IAGF,MAAM,WAAW,GAAG,KAClB,OAAO,QACP;KACE,UAAU,OAAO;KACjB,GAAI,OAAO,SAAS,EAAE,SAAS,OAAO,QAAQ,GAAG,EAAE;KACnD,GAAI,OAAO,WAAW,EAAE,UAAU,OAAO,UAAU,GAAG,EAAE;KACxD,8BAA8B;KAC/B,EACD,oBACD;AAED,QAAI,UAAU;AACZ,eAAU;AACV,aAAQ,SAAS,EAAE,SAAS,cAAc,CAAC;AAE3C,SAAI,SAAS,OAAO,cAAc,MAChC,SAAQ,kBAAkB;;;GAIhC,eAAe,SAAS;AACtB,QAAI,CAAC,QACH;AAGF,QAAI,QAAQ,OAAO,cAAc,MAC/B,SAAQ,mBAAmB;QAE3B,SAAQ,kBAAkB;;GAG9B,YAAY;AACV,aAAS,OAAO;AAChB,cAAU;;GAEb;EACF"}