@classytic/arc-next 0.15.0 → 0.15.1

package/dist/api.d.ts

@@ -114,9 +114,33 @@ interface BaseApiConfig {
 }
 declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   readonly entity: string;
-  readonly config: Required<Omit<BaseApiConfig, "client">>;
-  readonly baseUrl: string;
+  /**
+   * `basePath` stays OPTIONAL here — it holds the explicit per-instance
+   * override and nothing else. The resolved value is {@link basePath}, which is
+   * computed per read; baking it in would defeat the whole point (see below).
+   */
+  readonly config: Required<Omit<BaseApiConfig, "client" | "basePath">> & Pick<BaseApiConfig, "basePath">;
   private readonly requestFn;
+  /**
+   * Per-instance override → the deployment's declared prefix → `/api/v1`.
+   *
+   * The middle step is what lets a package construct its own API internally and
+   * still land on a host mounted elsewhere. Without it the only options were
+   * "every consumer passes `basePath`" — impossible for an instance a package
+   * owns — or "every host mounts at `/api/v1`".
+   *
+   * ## Why this is a GETTER and not resolved in the constructor
+   *
+   * `configureClient()` runs inside a `"use client"` provider, which is LATER
+   * than module evaluation. A package's API instance is created at import time,
+   * so a constructor-time read would capture `/api/v1` before the deployment
+   * ever declared `/api`, and the fallback would win permanently — producing a
+   * 404 that renders as an empty list, which is the failure this was meant to
+   * fix. An explicit `basePath` is unaffected either way.
+   */
+  get basePath(): string;
+  /** `{basePath}/{entity}` — the resource root every request is built from. */
+  get baseUrl(): string;
   constructor(entity: string, config?: BaseApiConfig);
   /** Merge per-instance headers into request options */
   private withHeaders;

package/dist/api.js

@@ -1,4 +1,4 @@
-import { createQueryString, handleApiRequest } from "./client.js";
+import { createQueryString, getBasePath, handleApiRequest } from "./client.js";
 import { STANDARD_RESERVED_PARAMS } from "@classytic/repo-core/query-parser";
 
 //#region src/api.ts
@@ -9,15 +9,43 @@ for (const verb of [
 ]) if (!STANDARD_RESERVED_PARAMS.has(verb)) throw new Error(`[arc-next] dispatch verb '${verb}' is not in repo-core STANDARD_RESERVED_PARAMS`);
 var BaseApi = class {
 	entity;
+	/**
+	* `basePath` stays OPTIONAL here — it holds the explicit per-instance
+	* override and nothing else. The resolved value is {@link basePath}, which is
+	* computed per read; baking it in would defeat the whole point (see below).
+	*/
 	config;
-	baseUrl;
 	requestFn;
+	/**
+	* Per-instance override → the deployment's declared prefix → `/api/v1`.
+	*
+	* The middle step is what lets a package construct its own API internally and
+	* still land on a host mounted elsewhere. Without it the only options were
+	* "every consumer passes `basePath`" — impossible for an instance a package
+	* owns — or "every host mounts at `/api/v1`".
+	*
+	* ## Why this is a GETTER and not resolved in the constructor
+	*
+	* `configureClient()` runs inside a `"use client"` provider, which is LATER
+	* than module evaluation. A package's API instance is created at import time,
+	* so a constructor-time read would capture `/api/v1` before the deployment
+	* ever declared `/api`, and the fallback would win permanently — producing a
+	* 404 that renders as an empty list, which is the failure this was meant to
+	* fix. An explicit `basePath` is unaffected either way.
+	*/
+	get basePath() {
+		return this.config.basePath ?? getBasePath() ?? "/api/v1";
+	}
+	/** `{basePath}/{entity}` — the resource root every request is built from. */
+	get baseUrl() {
+		return `${this.basePath}/${this.entity}`;
+	}
 	constructor(entity, config = {}) {
 		this.entity = entity;
 		const client = config.client;
 		this.requestFn = typeof client === "function" ? (method, endpoint, options) => client().request(method, endpoint, options) : client?.request ?? handleApiRequest;
 		this.config = {
-			basePath: config.basePath ?? "/api/v1",
+			...config.basePath !== void 0 ? { basePath: config.basePath } : {},
 			defaultParams: {
 				limit: 10,
 				page: 1,
@@ -26,7 +54,6 @@ var BaseApi = class {
 			cache: config.cache ?? "no-store",
 			headers: { ...config.headers || {} }
 		};
-		this.baseUrl = `${this.config.basePath}/${this.entity}`;
 	}
 	/** Merge per-instance headers into request options */
 	withHeaders(options) {

package/dist/client.d.ts

@@ -278,6 +278,23 @@ interface ClientEncryptionConfig {
 }
 interface ClientConfig {
   baseUrl: string;
+  /**
+   * Route prefix every API is mounted under, when it is not `/api/v1`.
+   *
+   * `BaseApi` defaults each instance to `/api/v1` and takes a per-instance
+   * `basePath` override. That covers an app's OWN api classes and nothing else:
+   * a package that constructs its own API internally — erp-shell's permission
+   * `platformApi`, an SDK preset — has no seam to be told, so on a host mounted
+   * anywhere but `/api/v1` it silently requests a URL that does not exist and
+   * the feature reads as "no data" rather than as a misconfiguration.
+   *
+   * Setting it here makes the mount point a property of the DEPLOYMENT, stated
+   * once, which is what it actually is. A per-instance `basePath` still wins,
+   * so nothing that already passes one changes.
+   *
+   * @example configureClient({ baseUrl, basePath: '/api' }) // host mounts at /api
+   */
+  basePath?: string;
   internalApiKey?: string;
   defaultHeaders?: Record<string, string>;
   /**
@@ -457,6 +474,15 @@ declare function configureClient(config: ClientConfig): void;
 declare function getAuthMode(): "bearer" | "cookie" | "header";
 /** Get the configured base URL. Returns empty string if not configured. */
 declare function getBaseUrl(): string;
+/**
+ * The deployment's route prefix, or `null` when it has not declared one.
+ *
+ * `null` rather than the `/api/v1` default on purpose: the default belongs to
+ * `BaseApi`, which is the one place that should own it. Returning it here would
+ * put the same literal in two files, and the next person to change one would
+ * have no way to know about the other.
+ */
+declare function getBasePath(): string | null;
 /** Whether auto-idempotency is enabled on the global client. */
 declare function isAutoIdempotency(): boolean;
 /**
@@ -1016,4 +1042,4 @@ declare const arc: {
   delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
 };
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, ServerClientConfig, StreamUrlProtocol, TextResponse, TierRequirement, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, ServerClientConfig, StreamUrlProtocol, TextResponse, TierRequirement, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBasePath, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };

package/dist/client.js

@@ -337,6 +337,17 @@ function getAuthMode() {
 function getBaseUrl() {
 	return clientConfig?.baseUrl ?? "";
 }
+/**
+* The deployment's route prefix, or `null` when it has not declared one.
+*
+* `null` rather than the `/api/v1` default on purpose: the default belongs to
+* `BaseApi`, which is the one place that should own it. Returning it here would
+* put the same literal in two files, and the next person to change one would
+* have no way to know about the other.
+*/
+function getBasePath() {
+	return clientConfig?.basePath ?? null;
+}
 /** Whether auto-idempotency is enabled on the global client. */
 function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
@@ -1276,4 +1287,4 @@ const arc = {
 };
 
 //#endregion
-export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBasePath, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,