@trokky/client 2.0.3

package/dist/media/url-builder.js

@@ -0,0 +1,280 @@
+/**
+ * Fluent Image URL Builder
+ * Provides a chainable API for building media URLs with transformations
+ *
+ * Inspired by Sanity's @sanity/image-url builder
+ */
+/**
+ * Fluent builder for constructing media URLs with transformations
+ *
+ * @example
+ * ```typescript
+ * const url = client.imageUrl(article.featuredImage)
+ *   .width(800)
+ *   .height(400)
+ *   .format('webp')
+ *   .quality(85)
+ *   .url()
+ * ```
+ */
+export class ImageUrlBuilder {
+    constructor(options) {
+        this.options = options;
+        this.mediaId = null;
+    }
+    /**
+     * Set the image source from a media field value
+     */
+    image(source) {
+        if (!source) {
+            this.mediaId = null;
+            return this;
+        }
+        if (typeof source === 'string') {
+            this.mediaId = source;
+        }
+        else if (source.asset?._ref) {
+            this.mediaId = source.asset._ref;
+        }
+        else {
+            this.mediaId = null;
+        }
+        return this;
+    }
+    /**
+     * Set image width
+     */
+    width(w) {
+        this._width = Math.round(w);
+        return this;
+    }
+    /**
+     * Set image height
+     */
+    height(h) {
+        this._height = Math.round(h);
+        return this;
+    }
+    /**
+     * Set both width and height
+     */
+    size(w, h) {
+        this._width = Math.round(w);
+        this._height = Math.round(h);
+        return this;
+    }
+    /**
+     * Set image format
+     */
+    format(fmt) {
+        this._format = fmt;
+        return this;
+    }
+    /**
+     * Set image quality (1-100)
+     */
+    quality(q) {
+        this._quality = Math.max(1, Math.min(100, Math.round(q)));
+        return this;
+    }
+    /**
+     * Set image fit mode
+     */
+    fit(mode) {
+        this._fit = mode;
+        return this;
+    }
+    /**
+     * Use a predefined variant (e.g., 'thumbnail', 'medium', 'large')
+     * When a variant is set, other transformations are ignored
+     */
+    variant(name) {
+        this._variant = name;
+        return this;
+    }
+    /**
+     * Apply blur effect (0-100)
+     */
+    blur(amount) {
+        this._blur = Math.max(0, Math.min(100, amount));
+        return this;
+    }
+    /**
+     * Apply sharpening (0-100)
+     */
+    sharpen(amount) {
+        this._sharpen = Math.max(0, Math.min(100, amount));
+        return this;
+    }
+    /**
+     * Convert to grayscale
+     */
+    grayscale() {
+        this._grayscale = true;
+        return this;
+    }
+    // Convenience presets
+    /**
+     * Preset for thumbnail size (200x200 cover)
+     */
+    thumbnail() {
+        return this.variant('thumbnail');
+    }
+    /**
+     * Preset for medium size
+     */
+    medium() {
+        return this.variant('medium');
+    }
+    /**
+     * Preset for large size
+     */
+    large() {
+        return this.variant('large');
+    }
+    /**
+     * Get the original file without transformations
+     */
+    original() {
+        this._variant = 'original';
+        return this;
+    }
+    /**
+     * Auto-select best format for browser
+     */
+    auto() {
+        this._format = 'auto';
+        return this;
+    }
+    /**
+     * Build and return the URL string
+     */
+    url() {
+        if (!this.mediaId) {
+            return null;
+        }
+        const isProxy = !!this.options.proxyPath;
+        // When using proxyPath, it replaces the full path (e.g., '/media')
+        // When using baseUrl, we need to add /media prefix
+        const basePath = isProxy
+            ? this.options.proxyPath
+            : `${this.options.baseUrl}/media`;
+        // Build URL with transformation parameters
+        const params = new URLSearchParams();
+        // For proxy mode with variants, convert to width params
+        if (isProxy && this._variant && this._variant !== 'original') {
+            const variantWidths = {
+                thumbnail: 300,
+                medium: 800,
+                large: 1200
+            };
+            const width = variantWidths[this._variant];
+            if (width) {
+                params.set('w', width.toString());
+            }
+        }
+        else {
+            // Use explicit width/height if set
+            if (this._width)
+                params.set('w', this._width.toString());
+            if (this._height)
+                params.set('h', this._height.toString());
+        }
+        if (this._format && this._format !== 'auto')
+            params.set('fm', this._format);
+        if (this._quality)
+            params.set('q', this._quality.toString());
+        if (this._fit)
+            params.set('fit', this._fit);
+        if (this._blur)
+            params.set('blur', this._blur.toString());
+        if (this._sharpen)
+            params.set('sharp', this._sharpen.toString());
+        if (this._grayscale)
+            params.set('grayscale', '1');
+        const queryString = params.toString();
+        // For non-proxy mode with variants, use the /variants/ path
+        if (!isProxy && this._variant) {
+            if (this._variant === 'original') {
+                return `${basePath}/${this.mediaId}/file`;
+            }
+            return `${basePath}/${this.mediaId}/variants/${this._variant}`;
+        }
+        // Return URL with query params
+        return `${basePath}/${this.mediaId}/file${queryString ? `?${queryString}` : ''}`;
+    }
+    /**
+     * Build URL string (alias for url())
+     */
+    toString() {
+        return this.url() || '';
+    }
+}
+/**
+ * Create an image URL builder factory
+ */
+export function createImageUrlBuilder(options) {
+    return function urlFor(source) {
+        return new ImageUrlBuilder(options).image(source);
+    };
+}
+/**
+ * Get responsive srcset for an image
+ *
+ * @example
+ * ```typescript
+ * const srcset = getSrcSet(article.image, {
+ *   baseUrl: 'http://localhost:3000/api',
+ *   widths: [400, 800, 1200]
+ * })
+ * // Returns: "/media/abc123/file?w=400 400w, /media/abc123/file?w=800 800w, ..."
+ * ```
+ */
+export function getSrcSet(source, options) {
+    if (!source?.asset?._ref) {
+        return null;
+    }
+    const mediaId = source.asset._ref;
+    const isProxy = !!options.proxyPath;
+    // When using proxyPath, it replaces the full path (e.g., '/media')
+    // When using baseUrl, we need to add /media prefix
+    const basePath = isProxy
+        ? options.proxyPath
+        : `${options.baseUrl}/media`;
+    // If using named variants (only for non-proxy mode)
+    if (options.variants && !isProxy) {
+        const variantWidths = {
+            thumbnail: 300,
+            medium: 800,
+            large: 1200,
+            original: 1920
+        };
+        return options.variants
+            .map(variant => {
+            const width = variantWidths[variant] || 800;
+            const url = variant === 'original'
+                ? `${basePath}/${mediaId}/file`
+                : `${basePath}/${mediaId}/variants/${variant}`;
+            return `${url} ${width}w`;
+        })
+            .join(', ');
+    }
+    // Use custom widths or defaults (works for both proxy and non-proxy)
+    const widths = options.widths || [400, 800, 1200, 1920];
+    return widths
+        .map(w => `${basePath}/${mediaId}/file?w=${w} ${w}w`)
+        .join(', ');
+}
+/**
+ * Get the best variant for a given viewport width
+ */
+export function getBestVariant(maxWidth) {
+    if (maxWidth <= 200)
+        return 'thumbnail';
+    if (maxWidth <= 800)
+        return 'medium';
+    if (maxWidth <= 1200)
+        return 'large';
+    return 'original';
+}
+//# sourceMappingURL=url-builder.js.map

package/dist/media/url-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-builder.js","sourceRoot":"","sources":["../../src/media/url-builder.ts"],"names":[],"mappings":"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"}

package/dist/query/builder.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Fluent Query Builder
+ * Provides a chainable API for building document queries with reference expansion
+ */
+import type { HttpClient } from '../http/client.js';
+import type { CacheManager } from '../cache/manager.js';
+import type { BaseDocument } from '../types/index.js';
+export interface QueryBuilderOptions {
+    /** Use cache for this query */
+    useCache?: boolean;
+    /** Disable cache busting timestamp */
+    noTimestamp?: boolean;
+}
+export interface ExpandConfig {
+    /** Field name to expand */
+    field: string;
+    /** Whether it's an array of references */
+    isArray?: boolean;
+    /** Nested expansions */
+    expand?: string[];
+}
+/**
+ * Fluent query builder for Trokky documents
+ *
+ * @example
+ * ```typescript
+ * const articles = await client
+ *   .from('article')
+ *   .published()
+ *   .expand('category')
+ *   .expand('author')
+ *   .sort({ _createdAt: 'desc' })
+ *   .limit(10)
+ *   .fetch()
+ * ```
+ */
+export declare class QueryBuilder<T extends BaseDocument = BaseDocument> {
+    private http;
+    private cache;
+    private _type;
+    private _filter;
+    private _sort;
+    private _limit?;
+    private _offset?;
+    private _select?;
+    private _expand;
+    private _options;
+    constructor(http: HttpClient, cache: CacheManager, type: string);
+    /**
+     * Filter by published status (_status === 'published')
+     */
+    published(): this;
+    /**
+     * Filter by draft status (_status === 'draft')
+     */
+    draft(): this;
+    /**
+     * Add filter conditions
+     * @param conditions Filter object or field name
+     * @param value Value if first param is field name
+     */
+    where(conditions: Record<string, any>): this;
+    where(field: string, value: any): this;
+    /**
+     * Add equality filter
+     */
+    eq(field: string, value: any): this;
+    /**
+     * Add not-equal filter
+     */
+    neq(field: string, value: any): this;
+    /**
+     * Add greater-than filter
+     */
+    gt(field: string, value: any): this;
+    /**
+     * Add greater-than-or-equal filter
+     */
+    gte(field: string, value: any): this;
+    /**
+     * Add less-than filter
+     */
+    lt(field: string, value: any): this;
+    /**
+     * Add less-than-or-equal filter
+     */
+    lte(field: string, value: any): this;
+    /**
+     * Add in-array filter
+     */
+    in(field: string, values: any[]): this;
+    /**
+     * Add not-in-array filter
+     */
+    notIn(field: string, values: any[]): this;
+    /**
+     * Add text search filter
+     */
+    search(term: string, fields?: string[]): this;
+    /**
+     * Expand a reference field (resolve the reference to full document)
+     * @param field Field name to expand. Use 'field[]' syntax for array references
+     */
+    expand(field: string): this;
+    /**
+     * Set sort order
+     * @param sortConfig Sort configuration object
+     */
+    sort(sortConfig: Record<string, 'asc' | 'desc' | 1 | -1>): this;
+    /**
+     * Sort by field ascending
+     */
+    sortAsc(field: string): this;
+    /**
+     * Sort by field descending
+     */
+    sortDesc(field: string): this;
+    /**
+     * Sort by creation date (newest first)
+     */
+    newest(): this;
+    /**
+     * Sort by creation date (oldest first)
+     */
+    oldest(): this;
+    /**
+     * Limit number of results
+     */
+    limit(count: number): this;
+    /**
+     * Skip first N results
+     */
+    offset(count: number): this;
+    /**
+     * Skip first N results (alias for offset)
+     */
+    skip(count: number): this;
+    /**
+     * Select specific fields only
+     */
+    select(...fields: string[]): this;
+    /**
+     * Disable caching for this query
+     */
+    noCache(): this;
+    /**
+     * Add cache-busting timestamp to prevent stale data
+     */
+    fresh(): this;
+    /**
+     * Execute the query and return results
+     */
+    fetch(): Promise<T[]>;
+    /**
+     * Execute the query and return results with metadata
+     */
+    fetchWithMeta(): Promise<{
+        documents: T[];
+        total?: number;
+        offset?: number;
+        limit?: number;
+        hasMore?: boolean;
+    }>;
+    /**
+     * Get first result or null
+     */
+    first(): Promise<T | null>;
+    /**
+     * Get count of matching documents
+     */
+    count(): Promise<number>;
+    /**
+     * Check if any documents match the query
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Check if references have already been expanded by the server
+     */
+    private hasExpandedReferences;
+    /**
+     * Expand references in documents
+     */
+    private expandReferences;
+    /**
+     * Check if a value is a reference object
+     */
+    private isReference;
+    /**
+     * Get a nested value from an object using dot notation path
+     * @param obj The object to traverse
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     */
+    private getNestedValue;
+    /**
+     * Set a nested value in an object using dot notation path
+     * @param obj The object to modify
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     * @param value The value to set
+     */
+    private setNestedValue;
+    /**
+     * Infer type from reference ID (e.g., 'category-abc123' -> 'category')
+     */
+    private inferTypeFromRef;
+    /**
+     * Extract document from API response
+     */
+    private extractDocument;
+    /**
+     * Fetch a single referenced document
+     */
+    private fetchReference;
+}
+/**
+ * Singleton query builder for fetching a single document by type
+ */
+export declare class SingletonBuilder<T extends BaseDocument = BaseDocument> {
+    private http;
+    private cache;
+    private _type;
+    private _id?;
+    private _expand;
+    private _options;
+    constructor(http: HttpClient, cache: CacheManager, _type: string, _id?: string | undefined);
+    /**
+     * Expand a reference field
+     */
+    expand(field: string): this;
+    /**
+     * Disable caching
+     */
+    noCache(): this;
+    /**
+     * Fetch fresh data with cache busting
+     */
+    fresh(): this;
+    /**
+     * Execute and return the singleton document
+     */
+    fetch(): Promise<T | null>;
+    /**
+     * Check if references have already been expanded by the server
+     */
+    private hasExpandedReferences;
+    /**
+     * Expand references in a single document
+     */
+    private expandReferences;
+    private isReference;
+    /**
+     * Get a nested value from an object using dot notation path
+     * @param obj The object to traverse
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     */
+    private getNestedValue;
+    /**
+     * Set a nested value in an object using dot notation path
+     * @param obj The object to modify
+     * @param path Dot-separated path (e.g., 'documentation.featuredDocument')
+     * @param value The value to set
+     */
+    private setNestedValue;
+    private inferTypeFromRef;
+    /**
+     * Extract document from API response
+     */
+    private extractDocument;
+    private fetchReference;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/query/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/query/builder.ts"],"names":[],"mappings":"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"}