@storyblok/management-api-client 0.1.0

package/src/core/pathSerializer.ts

@@ -0,0 +1,179 @@
+interface SerializeOptions<T>
+  extends SerializePrimitiveOptions,
+    SerializerOptions<T> {}
+
+interface SerializePrimitiveOptions {
+  allowReserved?: boolean;
+  name: string;
+}
+
+export interface SerializerOptions<T> {
+  /**
+   * @default true
+   */
+  explode: boolean;
+  style: T;
+}
+
+export type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
+export type ArraySeparatorStyle = ArrayStyle | MatrixStyle;
+type MatrixStyle = 'label' | 'matrix' | 'simple';
+export type ObjectStyle = 'form' | 'deepObject';
+type ObjectSeparatorStyle = ObjectStyle | MatrixStyle;
+
+interface SerializePrimitiveParam extends SerializePrimitiveOptions {
+  value: string;
+}
+
+export const separatorArrayExplode = (style: ArraySeparatorStyle) => {
+  switch (style) {
+    case 'label':
+      return '.';
+    case 'matrix':
+      return ';';
+    case 'simple':
+      return ',';
+    default:
+      return '&';
+  }
+};
+
+export const separatorArrayNoExplode = (style: ArraySeparatorStyle) => {
+  switch (style) {
+    case 'form':
+      return ',';
+    case 'pipeDelimited':
+      return '|';
+    case 'spaceDelimited':
+      return '%20';
+    default:
+      return ',';
+  }
+};
+
+export const separatorObjectExplode = (style: ObjectSeparatorStyle) => {
+  switch (style) {
+    case 'label':
+      return '.';
+    case 'matrix':
+      return ';';
+    case 'simple':
+      return ',';
+    default:
+      return '&';
+  }
+};
+
+export const serializeArrayParam = ({
+  allowReserved,
+  explode,
+  name,
+  style,
+  value,
+}: SerializeOptions<ArraySeparatorStyle> & {
+  value: unknown[];
+}) => {
+  if (!explode) {
+    const joinedValues = (
+      allowReserved ? value : value.map((v) => encodeURIComponent(v as string))
+    ).join(separatorArrayNoExplode(style));
+    switch (style) {
+      case 'label':
+        return `.${joinedValues}`;
+      case 'matrix':
+        return `;${name}=${joinedValues}`;
+      case 'simple':
+        return joinedValues;
+      default:
+        return `${name}=${joinedValues}`;
+    }
+  }
+
+  const separator = separatorArrayExplode(style);
+  const joinedValues = value
+    .map((v) => {
+      if (style === 'label' || style === 'simple') {
+        return allowReserved ? v : encodeURIComponent(v as string);
+      }
+
+      return serializePrimitiveParam({
+        allowReserved,
+        name,
+        value: v as string,
+      });
+    })
+    .join(separator);
+  return style === 'label' || style === 'matrix'
+    ? separator + joinedValues
+    : joinedValues;
+};
+
+export const serializePrimitiveParam = ({
+  allowReserved,
+  name,
+  value,
+}: SerializePrimitiveParam) => {
+  if (value === undefined || value === null) {
+    return '';
+  }
+
+  if (typeof value === 'object') {
+    throw new Error(
+      'Deeply-nested arrays/objects aren’t supported. Provide your own `querySerializer()` to handle these.',
+    );
+  }
+
+  return `${name}=${allowReserved ? value : encodeURIComponent(value)}`;
+};
+
+export const serializeObjectParam = ({
+  allowReserved,
+  explode,
+  name,
+  style,
+  value,
+  valueOnly,
+}: SerializeOptions<ObjectSeparatorStyle> & {
+  value: Record<string, unknown> | Date;
+  valueOnly?: boolean;
+}) => {
+  if (value instanceof Date) {
+    return valueOnly ? value.toISOString() : `${name}=${value.toISOString()}`;
+  }
+
+  if (style !== 'deepObject' && !explode) {
+    let values: string[] = [];
+    Object.entries(value).forEach(([key, v]) => {
+      values = [
+        ...values,
+        key,
+        allowReserved ? (v as string) : encodeURIComponent(v as string),
+      ];
+    });
+    const joinedValues = values.join(',');
+    switch (style) {
+      case 'form':
+        return `${name}=${joinedValues}`;
+      case 'label':
+        return `.${joinedValues}`;
+      case 'matrix':
+        return `;${name}=${joinedValues}`;
+      default:
+        return joinedValues;
+    }
+  }
+
+  const separator = separatorObjectExplode(style);
+  const joinedValues = Object.entries(value)
+    .map(([key, v]) =>
+      serializePrimitiveParam({
+        allowReserved,
+        name: style === 'deepObject' ? `${name}[${key}]` : key,
+        value: v as string,
+      }),
+    )
+    .join(separator);
+  return style === 'label' || style === 'matrix'
+    ? separator + joinedValues
+    : joinedValues;
+};

package/src/core/types.ts

@@ -0,0 +1,118 @@
+import type { Auth, AuthToken } from './auth';
+import type {
+  BodySerializer,
+  QuerySerializer,
+  QuerySerializerOptions,
+} from './bodySerializer';
+
+export interface Client<
+  RequestFn = never,
+  Config = unknown,
+  MethodFn = never,
+  BuildUrlFn = never,
+> {
+  /**
+   * Returns the final request URL.
+   */
+  buildUrl: BuildUrlFn;
+  connect: MethodFn;
+  delete: MethodFn;
+  get: MethodFn;
+  getConfig: () => Config;
+  head: MethodFn;
+  options: MethodFn;
+  patch: MethodFn;
+  post: MethodFn;
+  put: MethodFn;
+  request: RequestFn;
+  setConfig: (config: Config) => Config;
+  trace: MethodFn;
+}
+
+export interface Config {
+  /**
+   * Auth token or a function returning auth token. The resolved value will be
+   * added to the request payload as defined by its `security` array.
+   */
+  auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+  /**
+   * A function for serializing request body parameter. By default,
+   * {@link JSON.stringify()} will be used.
+   */
+  bodySerializer?: BodySerializer | null;
+  /**
+   * An object containing any HTTP headers that you want to pre-populate your
+   * `Headers` object with.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+   */
+  headers?:
+    | RequestInit['headers']
+    | Record<
+        string,
+        | string
+        | number
+        | boolean
+        | (string | number | boolean)[]
+        | null
+        | undefined
+        | unknown
+      >;
+  /**
+   * The request method.
+   *
+   * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+   */
+  method?:
+    | 'CONNECT'
+    | 'DELETE'
+    | 'GET'
+    | 'HEAD'
+    | 'OPTIONS'
+    | 'PATCH'
+    | 'POST'
+    | 'PUT'
+    | 'TRACE';
+  /**
+   * A function for serializing request query parameters. By default, arrays
+   * will be exploded in form style, objects will be exploded in deepObject
+   * style, and reserved characters are percent-encoded.
+   *
+   * This method will have no effect if the native `paramsSerializer()` Axios
+   * API function is used.
+   *
+   * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+   */
+  querySerializer?: QuerySerializer | QuerySerializerOptions;
+  /**
+   * A function validating request data. This is useful if you want to ensure
+   * the request conforms to the desired shape, so it can be safely sent to
+   * the server.
+   */
+  requestValidator?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function transforming response data before it's returned. This is useful
+   * for post-processing data, e.g. converting ISO strings into Date objects.
+   */
+  responseTransformer?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function validating response data. This is useful if you want to ensure
+   * the response conforms to the desired shape, so it can be safely passed to
+   * the transformers and returned to the user.
+   */
+  responseValidator?: (data: unknown) => Promise<unknown>;
+}
+
+type IsExactlyNeverOrNeverUndefined<T> = [T] extends [never]
+  ? true
+  : [T] extends [never | undefined]
+    ? [undefined] extends [T]
+      ? false
+      : true
+    : false;
+
+export type OmitNever<T extends Record<string, unknown>> = {
+  [K in keyof T as IsExactlyNeverOrNeverUndefined<T[K]> extends true
+    ? never
+    : K]: T[K];
+};

package/src/index.ts

@@ -0,0 +1,129 @@
+// Import generated SDKs with shared client support
+import { createClient } from './client';
+import type { Client } from './client/types';
+import { getManagementBaseUrl, type Region } from '@storyblok/region-helper';
+import { sdkRegistry, SdkRegistryInstance } from './sdk-registry.generated';
+
+type PersonalAccessToken = {
+  accessToken: string;
+}
+
+type OAuthToken = {
+  oauthToken: string;
+}
+
+export interface ManagementApiClientConfig<ThrowOnError extends boolean = false> {
+  token: PersonalAccessToken | OAuthToken;
+  region?: Region;
+  baseUrl?: string; // Override for custom endpoints
+  headers?: Record<string, string>;
+  throwOnError?: ThrowOnError;
+}
+
+export interface ManagementApiClient<ThrowOnError extends boolean = false> extends SdkRegistryInstance {}
+export class ManagementApiClient<ThrowOnError extends boolean = false> {
+  protected client: Client;
+  protected config: ManagementApiClientConfig<ThrowOnError>;
+  protected sdkCache: Record<string, Promise<any>> = {};
+
+  constructor(config: ManagementApiClientConfig<ThrowOnError>) {
+    this.config = config;
+    this.client = createClientInstance(config);
+
+    Object.entries(sdkRegistry).forEach(([name, Sdk]) => {
+      Object.defineProperty(this, name, {
+        get: () => new Sdk({ client: this.client }),
+        enumerable: true,
+        configurable: true
+      });
+    });
+  }
+
+
+  /**
+   * @returns The client's interceptors
+   * @example
+   * client.interceptors.request.use((request, options) => {
+   *   console.log('Request:', request);
+   *   return request;
+   * });
+   */
+  public get interceptors(): Client['interceptors'] {
+    return this.client.interceptors;
+  }
+
+  /**
+   * @param config - The configuration to set
+   * @example
+   * client.setConfig({ region: 'eu' });
+   */
+  setConfig(config: Partial<Omit<ManagementApiClientConfig, 'token'>>): void {
+    const { region, baseUrl, headers } = config;
+    
+    let finalBaseUrl = baseUrl;
+    if (region && !baseUrl) {
+      finalBaseUrl = getManagementBaseUrl(region, "https");
+    }
+    
+    if (finalBaseUrl) {
+      this.client.setConfig({ baseUrl: finalBaseUrl });
+    }
+    
+    if (headers) {
+      this.client.setConfig({ 
+        headers: {
+          'Content-Type': 'application/json',
+          ...getAuthHeader(this.config.token),
+          ...headers
+        }
+      });
+    }
+  }
+
+  /**
+   * @param token - The token to set
+   * @example
+   * client.setToken({ accessToken: '123' });
+   */
+  setToken(token: PersonalAccessToken | OAuthToken): void {
+    this.config.token = token;
+    this.client.setConfig({
+      headers: {
+        'Content-Type': 'application/json',
+        ...getAuthHeader(token),
+        ...this.config.headers
+      }
+    });
+  }
+}
+
+// Pure functions for client creation and setup
+function createClientInstance<ThrowOnError extends boolean = false>(
+  config: ManagementApiClientConfig<ThrowOnError>
+): Client {
+  const { token, region = "eu", baseUrl, headers = {}, throwOnError = false } = config;
+  
+  const finalBaseUrl = baseUrl || getManagementBaseUrl(region, 'https');
+  
+  return createClient({
+    baseUrl: finalBaseUrl,
+    headers: {
+      'Content-Type': 'application/json',
+      ...getAuthHeader(token),
+      ...headers
+    },
+    throwOnError: throwOnError ?? false
+  });
+}
+
+function getAuthHeader(token: PersonalAccessToken | OAuthToken): Record<string, string> {
+  return 'accessToken' in token ? {
+    'Authorization': token.accessToken
+  } : {
+    'Authorization': token.oauthToken
+  }
+}
+
+// Export client utilities
+export { createClient } from './client';
+export type { Client } from './client/types';

package/src/shared-client.ts

@@ -0,0 +1,13 @@
+// Shared client for all generated SDKs
+import { createClient, type Client, type Config } from './client';
+
+// Create a shared client instance that can be used by all generated SDKs
+export const sharedClient = createClient();
+
+// Export types for generated SDKs
+export type { Client, Config } from './client';
+
+// Helper to create a client with custom config
+export const createSharedClient = (config?: Config): Client => {
+  return createClient(config);
+}; 

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+
+    /* Linting */
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "examples", "dist"],
+  "exclude": ["node_modules", "src/**/*.cy.ts", "src/**/*.test.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: [
+    './src/index.ts',
+    './src/generated/**/types.gen.ts',
+  ],
+  outDir: './dist',
+  platform: "neutral",
+  format: ['esm', "commonjs"],
+  globalName: 'StoryblokManagementApiClient',
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  unbundle: true,
+  external: [
+    // Externalize generated client duplicates to reduce bundle size
+    "./src/generated/*/client/*",
+    "./src/generated/*/core/*"
+  ]
+});