@asteroidcms/core-utils 0.1.2 → 0.1.3

package/dist/client.d.ts

@@ -0,0 +1,229 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren } from 'react';
+import * as _apollo_client from '@apollo/client';
+import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient } from '@apollo/client';
+import { useMutation } from '@apollo/client/react';
+
+type AsteroidCMSConfig = {
+    /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
+    cmsUrl: string;
+    /** API key sent as the `x-api-key` header on every request. */
+    apiKey: string;
+    /** Optional path appended to `cmsUrl` for the GraphQL endpoint. Defaults to "/graphql". */
+    graphqlPath?: string;
+    /** Optional path appended to `cmsUrl` for canonical media. Defaults to "/media/canonical". */
+    mediaPath?: string;
+    /** Extra headers attached to every GraphQL request. */
+    headers?: Record<string, string>;
+    /** Called for every GraphQL/network error. Use this to wire your own toast/logger. */
+    onError?: (error: unknown) => void;
+    /** Optional cache options forwarded to the InMemoryCache constructor. */
+    cacheConfig?: InMemoryCacheConfig;
+    /** Escape hatch — override any field on the underlying ApolloClient. */
+    apolloOptions?: Partial<ApolloClientOptions>;
+    /** Provide a pre-built ApolloClient and skip the internal factory entirely. */
+    client?: ApolloClient;
+};
+type ResolvedAsteroidCMSConfig = Required<Pick<AsteroidCMSConfig, "cmsUrl" | "apiKey" | "graphqlPath" | "mediaPath">> & {
+    headers: Record<string, string>;
+    onError?: AsteroidCMSConfig["onError"];
+};
+
+type AsteroidCMSProviderProps = PropsWithChildren<AsteroidCMSConfig>;
+/**
+ * Root provider for `@asteroidcms/core-utils`.
+ *
+ * Wrap your app once at the top level:
+ *
+ * ```tsx
+ * <AsteroidCMSProvider cmsUrl="https://cms.example.com" apiKey="...">
+ *   <App />
+ * </AsteroidCMSProvider>
+ * ```
+ *
+ * Everything below — `useCmsContent`, `useCmsMutate`, `useCmsImage`,
+ * `<RichTextContent>` — picks up `cmsUrl` and `apiKey` from this provider.
+ */
+declare function AsteroidCMSProvider({ children, ...config }: AsteroidCMSProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useAsteroidCMSConfig(): ResolvedAsteroidCMSConfig;
+
+type FieldSelector$1 = string | {
+    field: string;
+    as?: string;
+};
+type ReferenceExpansion$1 = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
+};
+type ContentStatus = "DRAFT" | "PUBLISHED" | "ARCHIVED";
+type CmsSearchCondition = {
+    field: string;
+    value: string;
+    mode?: string;
+};
+type UseCmsContentOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
+    fullData?: boolean;
+    limit?: number;
+    offset?: number;
+    status?: ContentStatus;
+    filter?: Record<string, string | number | boolean | null>;
+    search?: CmsSearchCondition[];
+    variables?: Record<string, any>;
+};
+/**
+ * React hook for querying content from Asteroid CMS via a flexible GraphQL API.
+ *
+ * Supports single-entry fetches (`entrySlug`) and paginated/filtered lists,
+ * with arbitrarily nested reference expansion and field aliasing.
+ */
+declare function useCmsContent<T = unknown>({ schema_slug, entrySlug, select, fullData, limit, offset, status, filter, search, variables, }: UseCmsContentOptions): {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "empty";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+} | {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "complete";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+} | {
+    client: _apollo_client.ApolloClient;
+    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
+    previousData?: unknown;
+    networkStatus: _apollo_client.NetworkStatus;
+    startPolling: (pollInterval: number) => void;
+    stopPolling: () => void;
+    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
+    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
+    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
+        data: unknown;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    variables: _apollo_client.OperationVariables;
+    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
+        data: TFetchData | undefined;
+        error?: _apollo_client.ErrorLike;
+    }>;
+    dataState: "streaming";
+    loading: boolean;
+    error: _apollo_client.ErrorLike | undefined;
+    data: T | undefined;
+};
+
+type FieldSelector = string | {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type ReferenceExpansion = {
+    field: string;
+    as?: string;
+    single?: boolean;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+};
+type MutationType = "create" | "update" | "delete";
+type UseCmsMutateOptions = {
+    schema_slug: string;
+    entrySlug?: string;
+    select?: readonly (FieldSelector | ReferenceExpansion)[];
+    fullData?: boolean;
+    mutationType?: MutationType;
+    entryId?: string;
+    variables?: Record<string, any>;
+};
+/**
+ * React hook for mutating content in Asteroid CMS (`create` / `update` / `delete`).
+ * Uses the same selection syntax as `useCmsContent`.
+ */
+declare function useCmsMutate<TData = unknown>({ schema_slug, select, fullData, mutationType, entryId, variables: inputVariables, }: UseCmsMutateOptions): {
+    readonly data: TData | undefined;
+    readonly loading: boolean;
+    readonly called: boolean;
+    readonly client: _apollo_client.ApolloClient;
+    readonly reset: () => void;
+    readonly error: _apollo_client.ErrorLike | undefined;
+    readonly mutate: useMutation.MutationFunction<unknown, {
+        [x: string]: any;
+    }, _apollo_client.ApolloCache, "none">;
+};
+
+/** Hook variant that pulls `cmsUrl`/`mediaPath` from the provider. */
+declare function useCmsImage(): (id?: string) => string;
+
+/**
+ * Portable rich-text parser for CMS content.
+ *
+ * Zero runtime dependencies. Safe to copy into any consuming frontend.
+ *
+ * Pipeline:
+ *   1. Detect & migrate legacy "markdown-in-divs" content to clean semantic HTML.
+ *   2. Walk the HTML through a tag/attribute allowlist (strips <script>, event
+ *      handlers, javascript: URLs, unknown tags).
+ *   3. Merge per-tag and per-variant classes from `options.classMap`.
+ *
+ * Idempotent: parseRichText(parseRichText(x, opts), opts) === parseRichText(x, opts).
+ */
+type RichTextClassKey = "p" | "br" | "hr" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "ul" | "ol" | "li" | "blockquote" | "pre" | "code" | "inlineCode" | "a" | "strong" | "em" | "u" | "s" | "kbd" | "table" | "tableWrapper" | "thead" | "tbody" | "tr" | "th" | "td" | "figure" | "figcaption" | "img" | "span" | "callout" | "calloutTitle";
+type RichTextClassMap = Partial<Record<RichTextClassKey, string>> & {
+    /** Variant overrides keyed as `${matchKey}:${variant}`, e.g. "callout:warning". */
+    variants?: Record<string, string>;
+};
+
+interface RichTextContentProps {
+    html: string;
+    classMap?: RichTextClassMap;
+    /** Wrapper element. Defaults to `div`. Use `article` for blog content. */
+    as?: keyof React.JSX.IntrinsicElements;
+    className?: string;
+}
+declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
+    ref: react.MutableRefObject<HTMLElement | null>;
+    className: string | undefined;
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+}, HTMLElement>;
+
+export { AsteroidCMSProvider, type AsteroidCMSProviderProps, RichTextContent, type UseCmsContentOptions, type UseCmsMutateOptions, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };