t1y-sdk-js 5.0.0

package/dist/index.d.ts

@@ -0,0 +1,920 @@
+/**
+ * Configuration for initializing the t1yOS client.
+ */
+interface T1YOSConfig {
+    /** Base URL of the t1yOS platform. Default: 'https://myapp.t1y.net' */
+    baseUrl?: string;
+    /** Application ID. Required, must be an integer >= 1001 */
+    appId: number;
+    /** API Key. Required, must be exactly 32 characters */
+    apiKey: string;
+    /** Secret Key. Required, must be exactly 32 characters */
+    secretKey: string;
+    /** Application version. Default: 0 */
+    version?: number;
+    /** Whether to enable safe mode (AES-256-GCM encryption). Default: false */
+    isSafeMode?: boolean;
+    /** Time format for createdAt/updatedAt fields. Default: 'YYYY-MM-DD HH:mm:ss' */
+    timeFormat?: string;
+    /** Time offset in seconds between client and server. Default: 0 */
+    offset?: number;
+}
+/**
+ * Internal configuration with all optional fields resolved to defaults.
+ */
+interface T1YOSInternalConfig {
+    baseUrl: string;
+    appId: number;
+    apiKey: string;
+    secretKey: string;
+    version: number;
+    isSafeMode: boolean;
+    timeFormat: string;
+    offset: number;
+}
+/** HTTP methods supported by the SDK */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+/**
+ * Standard API response wrapper returned by the t1yOS server.
+ */
+interface ApiResponse<T = unknown> {
+    code: number;
+    message: string;
+    data: T;
+}
+/** Response from insertOne */
+interface InsertResult {
+    objectId: string;
+}
+/** Response from insertMany */
+interface InsertManyResult {
+    objectIds: string[];
+    insertedCount: number;
+}
+/** Response from deleteOne / deleteOneByObjectId */
+interface DeleteResult {
+    deletedCount: number;
+}
+/** Response from deleteMany */
+interface DeleteManyResult {
+    deletedCount: number;
+}
+/** Response from updateOne / updateOneByObjectId */
+interface UpdateResult {
+    modifiedCount: number;
+}
+/** Response from updateMany */
+interface UpdateManyResult {
+    modifiedCount: number;
+}
+/** Response from findOne / findOneByObjectId / findOneByFilter */
+interface FindResult {
+    result: Record<string, unknown>;
+}
+/** Pagination metadata */
+interface Pagination {
+    totalItems: number;
+    totalPages: number;
+}
+/** Response from find (paginated query) */
+interface PaginationResult {
+    results: Record<string, unknown>[];
+    page: number;
+    size: number;
+    pagination: Pagination;
+}
+/** Response from aggregate */
+interface AggregateResult {
+    results: Record<string, unknown>[];
+}
+/** Init response from GET /init/:appId */
+interface InitResult {
+    unix: number;
+    is_safe_mode: boolean;
+}
+
+/**
+ * Marker type string representations that the server's GetDataTypes()
+ * recognizes and converts to native MongoDB/Go types.
+ *
+ * These are all literal string types for documentation/typing purposes.
+ * At runtime, the helper functions simply return these string values.
+ */
+/** ObjectID marker: ObjectID('24-char-hex') */
+type ObjectIDMarker = `ObjectID('${string}')`;
+/** Date marker: Date('RFC3339') */
+type DateMarker = `Date('${string}')`;
+/** DateTime marker: DateTime('RFC3339') */
+type DateTimeMarker = `DateTime('${string}')`;
+/** Timestamp marker: Timestamp('unix-seconds') */
+type TimestampMarker = `Timestamp('${string}')`;
+/** Boolean marker: Boolean(true) or Boolean(false) */
+type BooleanMarker = `Boolean(${string})`;
+/** Integer marker: Integer(N) */
+type IntegerMarker = `Integer(${number})`;
+/** Bigint marker: Bigint(N) */
+type BigintMarker = `Bigint(${number})`;
+/** Float marker: Float(N) */
+type FloatMarker = `Float(${number})`;
+/** Double marker: Double(N) */
+type DoubleMarker = `Double(${number})`;
+/** Array marker: Array(json) */
+type ArrayMarker = `Array(${string})`;
+/** Map marker: Map(json) */
+type MapMarker = `Map(${string})`;
+/** Map[] marker: Map[](json) */
+type MapArrayMarker = `Map[](${string})`;
+/** Null markers that the server converts to nil */
+type NullMarker = 'Null' | 'null' | 'NULL' | 'None' | 'none' | 'NONE' | 'Nil' | 'nil' | 'NIL' | '<nil>' | '';
+/** Undefined markers that the server converts to bson.Undefined */
+type UndefinedMarker = 'UNDEFINED' | 'Undefined';
+/** Time helper markers */
+type TimeNowMarker = 'time.Now()';
+type TimeNowUnixMarker = 'time.Now().Unix()';
+type TimeNowUnixNanoMarker = 'time.Now().UnixNano()';
+type TimeNowWeekdayMarker = 'time.Now().Weekday()';
+type TimeNowWeekdayChineseMarker = 'time.Now().Weekday().Chinese()';
+/**
+ * Union of all possible special type marker strings.
+ */
+type SpecialTypeMarker = ObjectIDMarker | DateMarker | DateTimeMarker | TimestampMarker | BooleanMarker | IntegerMarker | BigintMarker | FloatMarker | DoubleMarker | ArrayMarker | MapMarker | MapArrayMarker | NullMarker | UndefinedMarker | TimeNowMarker | TimeNowUnixMarker | TimeNowUnixNanoMarker | TimeNowWeekdayMarker | TimeNowWeekdayChineseMarker;
+
+/**
+ * T1Collection — Database collection class providing chainable CRUD and schema operations.
+ *
+ * Created via `client.db.collection('name')` — never instantiated directly.
+ */
+
+declare class T1Collection {
+    /** The parent T1YOS client */
+    private client;
+    /** The collection (table) name */
+    private name;
+    /**
+     * @internal — Use `client.db.collection(name)` instead.
+     */
+    constructor(client: T1YOS, name: string);
+    /**
+     * Insert one document into the collection.
+     *
+     * @param data - Document data (must be a non-empty plain object)
+     * @returns Response with the inserted document's ObjectID
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').insertOne({
+     *   name: 'Alice',
+     *   age: 25,
+     * })
+     * console.log(data.objectId) // '507f1f77bcf86cd799439011'
+     * ```
+     */
+    insertOne(data: Record<string, unknown>): Promise<ApiResponse<InsertResult>>;
+    /**
+     * Delete one document by ObjectID.
+     *
+     * @param objectId - 24-character hex ObjectID string
+     * @returns Response with deleted count
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('users').deleteById('507f1f77bcf86cd799439011')
+     * ```
+     */
+    deleteById(objectId: string): Promise<ApiResponse<DeleteResult>>;
+    /**
+     * Update one document by ObjectID.
+     *
+     * @param objectId - 24-character hex ObjectID string
+     * @param data - Update data (must be a non-empty plain object)
+     * @returns Response with modified count
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('users').updateById('507f1f77bcf86cd799439011', { name: 'Bob' })
+     * ```
+     */
+    updateById(objectId: string, data: Record<string, unknown>): Promise<ApiResponse<UpdateResult>>;
+    /**
+     * Find one document by ObjectID.
+     *
+     * @param objectId - 24-character hex ObjectID string
+     * @returns Response with the found document
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').findById('507f1f77bcf86cd799439011')
+     * console.log(data.result) // { _id: '507f1f77...', name: 'Alice', ... }
+     * ```
+     */
+    findById(objectId: string): Promise<ApiResponse<FindResult>>;
+    /**
+     * Delete one document matching the filter.
+     *
+     * @param filter - Query filter (must be a non-empty plain object)
+     * @returns Response with deleted count
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('users').deleteOne({ name: 'Alice' })
+     * ```
+     */
+    deleteOne(filter: Record<string, unknown>): Promise<ApiResponse<DeleteResult>>;
+    /**
+     * Update one document matching the filter.
+     *
+     * @param filter - Query filter to find the document
+     * @param body - Update data (MongoDB update operators like $set, $inc, etc.)
+     * @returns Response with modified count
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('users').updateOne(
+     *   { name: 'Alice' },
+     *   { $set: { age: 26 } }
+     * )
+     * ```
+     */
+    updateOne(filter: Record<string, unknown>, body: Record<string, unknown>): Promise<ApiResponse<UpdateResult>>;
+    /**
+     * Find one document matching the filter.
+     *
+     * @param filter - Query filter
+     * @returns Response with the found document (or null if not found)
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').findOne({ name: 'Alice' })
+     * ```
+     */
+    findOne(filter: Record<string, unknown>): Promise<ApiResponse<FindResult>>;
+    /**
+     * Insert multiple documents into the collection.
+     *
+     * @param dataList - Array of document data (each must be a non-empty plain object)
+     * @returns Response with inserted ObjectIDs and count
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').insertMany([
+     *   { name: 'Alice', age: 25 },
+     *   { name: 'Bob', age: 30 },
+     * ])
+     * console.log(data.insertedCount) // 2
+     * ```
+     */
+    insertMany(dataList: Record<string, unknown>[]): Promise<ApiResponse<InsertManyResult>>;
+    /**
+     * Delete multiple documents matching the filter.
+     *
+     * @param filter - Query filter (can be an empty object to match all)
+     * @returns Response with deleted count
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').deleteMany({ age: { $lt: 18 } })
+     * console.log(data.deletedCount) // 5
+     * ```
+     */
+    deleteMany(filter: Record<string, unknown>): Promise<ApiResponse<DeleteManyResult>>;
+    /**
+     * Update multiple documents matching the filter.
+     *
+     * @param filter - Query filter to match documents
+     * @param body - Update data (MongoDB update operators)
+     * @returns Response with modified count
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('users').updateMany(
+     *   { status: 'inactive' },
+     *   { $set: { status: 'archived' } }
+     * )
+     * ```
+     */
+    updateMany(filter: Record<string, unknown>, body: Record<string, unknown>): Promise<ApiResponse<UpdateManyResult>>;
+    /**
+     * Paginated find query with sorting and filtering.
+     *
+     * @param page - Page number (1-based, default: 1)
+     * @param size - Page size (1-100, default: 10)
+     * @param sort - Sort specification, e.g. `{ createdAt: -1 }` for newest first
+     * @param filter - Query filter
+     * @returns Response with paginated results and pagination metadata
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').find(
+     *   1,        // page
+     *   20,       // size
+     *   { createdAt: -1 },  // sort (newest first)
+     *   { age: { $gte: 18 } }  // filter
+     * )
+     * console.log(data.results)        // Array of documents
+     * console.log(data.pagination)     // { totalItems: 100, totalPages: 5 }
+     * ```
+     */
+    find(page?: number, size?: number, sort?: Record<string, number>, filter?: Record<string, unknown>): Promise<ApiResponse<PaginationResult>>;
+    /**
+     * Execute a MongoDB aggregation pipeline.
+     *
+     * @param pipeline - Array of aggregation stages
+     * @returns Response with aggregation results
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('orders').aggregate([
+     *   { $match: { status: 'completed' } },
+     *   { $group: { _id: '$category', total: { $sum: '$amount' } } },
+     *   { $sort: { total: -1 } },
+     * ])
+     * ```
+     */
+    aggregate(pipeline: Record<string, unknown>[]): Promise<ApiResponse<AggregateResult>>;
+    /**
+     * Count documents matching a filter.
+     *
+     * Uses `POST /v5/classes/:name/count` with the filter as the request body.
+     *
+     * @param filter - Query filter (can be an empty object for total count)
+     * @returns Response with `data.count`
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').count({ status: 'active' })
+     * console.log(data.count) // 42
+     * ```
+     */
+    count(filter?: Record<string, unknown>): Promise<ApiResponse<{
+        count: number;
+    }>>;
+    /**
+     * Get distinct values for a field, optionally filtered.
+     *
+     * Uses `POST /v5/classes/:name/distinct/:field` with the filter as the request body.
+     *
+     * @param fieldName - The field to get distinct values for
+     * @param filter - Optional filter to narrow the documents
+     * @returns Response with `data.results` containing distinct values
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('users').distinct('city')
+     * console.log(data.results) // ['Beijing', 'Shanghai', ...]
+     * ```
+     */
+    distinct(fieldName: string, filter?: Record<string, unknown>): Promise<ApiResponse<{
+        results: unknown[];
+    }>>;
+    /**
+     * Create this collection (table) in the application's database.
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('posts').create()
+     * ```
+     */
+    create(): Promise<ApiResponse>;
+    /**
+     * Clear all documents from this collection without dropping it.
+     *
+     * @returns Response with `data.deletedCount`
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.db.collection('temp').clear()
+     * console.log(data.deletedCount) // 150
+     * ```
+     */
+    clear(): Promise<ApiResponse<{
+        deletedCount: number;
+    }>>;
+    /**
+     * Drop (delete) this collection entirely.
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('old_collection').drop()
+     * ```
+     */
+    drop(): Promise<ApiResponse>;
+}
+
+/**
+ * T1YOS — Main client class for the t1yOS Serverless Platform SDK.
+ *
+ * Provides:
+ * - Initialization with server time sync
+ * - Chainable database operations via `db.collection(name)`
+ * - Cloud function invocation
+ * - Metadata retrieval
+ * - Cryptographic utilities
+ */
+
+/**
+ * Main T1Y client class.
+ *
+ * @example
+ * ```ts
+ * import { T1YOS } from 't1y-sdk-js'
+ *
+ * const client = new T1YOS({
+ *   appId: 1001,
+ *   apiKey: '4fd7448cdc684431a62d8a0111dc6973',
+ *   secretKey: '17b784e359c946ffa65eebbf9ce29752',
+ * })
+ *
+ * await client.init()
+ *
+ * // Database operations
+ * const { data } = await client.db.collection('users').insertOne({ name: 'Alice' })
+ * ```
+ */
+declare class T1YOS {
+    #private;
+    private config;
+    /**
+     * Database accessor providing chainable collection operations.
+     *
+     * @example
+     * ```ts
+     * await client.db.collection('users').insertOne({ name: 'Alice' })
+     * await client.db.collection('users').findOne({ name: 'Alice' })
+     * ```
+     */
+    readonly db: {
+        collection: (name: string) => T1Collection;
+        toObjectID: (id: string) => string;
+        getCollections: () => Promise<ApiResponse<{
+            results: string[];
+        }>>;
+    };
+    /**
+     * Create a new T1YOS client instance.
+     *
+     * @param config - Client configuration (appId, apiKey, secretKey are required)
+     *
+     * @throws {ValidationError} If required parameters are invalid
+     */
+    constructor(config: T1YOSConfig);
+    /**
+     * Initialize the SDK by syncing with the server.
+     *
+     * Calls `GET /init/:appId` to:
+     * 1. Get the server's current UTC Unix timestamp
+     * 2. Get the server's isSafeMode setting
+     *
+     * The time offset is computed as: `server.unix - client.unix`
+     * This offset is used for all subsequent request signing to prevent clock skew issues.
+     *
+     * @throws {T1YError} If the server returns an error (e.g., app not found, app disabled)
+     */
+    init(): Promise<void>;
+    /**
+     * Get application metadata.
+     *
+     * @param field - Optional field name to retrieve a specific metadata field
+     * @returns Metadata as key-value pairs, or a single field value if `field` is specified
+     *
+     * @example
+     * ```ts
+     * // Get all metadata
+     * const { data } = await client.getMeta()
+     * // data.results = { version: 1, collections: [...] }
+     *
+     * // Get a specific field
+     * const { data } = await client.getMeta('version')
+     * // data.result = 1
+     * ```
+     */
+    getMeta(field?: string): Promise<ApiResponse>;
+    /**
+     * Check if there's a newer version of the application available.
+     *
+     * Compares the server's `version` metadata field against the configured `version`.
+     *
+     * @returns `true` if the server version is greater than the client version
+     */
+    checkUpdate(): Promise<boolean>;
+    /**
+     * Call a cloud function (`.jsc` file).
+     *
+     * If `name` doesn't end with `.jsc`, it's auto-appended.
+     * If `name` ends with `/`, `index.jsc` is appended.
+     * If `name` ends with `.js`, it's replaced with `.jsc`.
+     *
+     * @param name - Function name or path (e.g., 'hello' or 'hello.jsc')
+     * @param params - Parameters to pass to the function
+     * @param enableSafeMode - Override safe mode for this call (defaults to client setting)
+     *
+     * @example
+     * ```ts
+     * const { data } = await client.callFunc('hello', { name: 'World' })
+     * ```
+     */
+    callFunc(name: string, params?: unknown, enableSafeMode?: boolean): Promise<ApiResponse>;
+    /**
+     * Core HTTP request method with full authentication and encryption.
+     *
+     * @param method - HTTP method (GET, POST, PUT, DELETE)
+     * @param path - API path (e.g., /v5/classes/users)
+     * @param params - Request parameters/body
+     * @param encryption - Override encryption (defaults to client.isSafeMode)
+     * @returns Typed API response
+     *
+     * @throws {T1YError} On API errors (non-2xx responses)
+     * @throws {Error} On network errors or timeouts
+     */
+    request<T = unknown>(method: HttpMethod, path: string, params?: unknown, encryption?: boolean): Promise<ApiResponse<T>>;
+    /**
+     * Validate an ObjectID hex string.
+     *
+     * @param idStr - 24-character hex string to validate
+     * @param name - Optional name for error messages (default: 'ObjectID')
+     * @returns `true` if valid
+     * @throws {ValidationError} If the string is not a valid ObjectID
+     */
+    assertObjectID(idStr: string, name?: string): boolean;
+    /** Check if a value is a non-null, non-array object with at least one key */
+    isNonEmptyObject(value: unknown): boolean;
+    /** Check if a value is a plain object (non-null, non-array) */
+    isPlainObject(value: unknown): boolean;
+    /** Check if a value is a non-empty array where every element is a non-empty object */
+    isNonEmptyArrayWithNonEmptyObjects(value: unknown): boolean;
+    /**
+     * Compute HMAC-SHA256 hash and return hex digest.
+     *
+     * @param message - The message to sign
+     * @param secret - The secret key
+     * @returns 64-character hex-encoded HMAC-SHA256
+     */
+    hmacSHA256(secret: string, message: string): string;
+    /**
+     * Verify an HMAC-SHA256 signature using constant-time comparison.
+     *
+     * @param secret - The secret key
+     * @param message - The message that was signed
+     * @param signature - The expected signature (hex string)
+     * @returns `true` if the signature matches
+     */
+    verifyHmacSHA256(secret: string, message: string, signature: string): boolean;
+}
+
+/**
+ * Create an ObjectID marker string that the server will convert to a MongoDB ObjectID.
+ *
+ * @param id - 24-character hexadecimal string
+ * @returns ObjectID marker string, e.g. `ObjectID('507f1f77bcf86cd799439011')`
+ *
+ * @example
+ * ```ts
+ * import { ObjectID } from 't1y-sdk-js'
+ *
+ * await db.collection('users').find(ObjectID('507f1f77bcf86cd799439011'))
+ * ```
+ */
+declare function ObjectID(id: string): `ObjectID('${string}')`;
+
+/**
+ * Create a Date marker string. The server converts this to a Go time.Time.
+ *
+ * @param dateStr - ISO 8601 / RFC 3339 date string
+ * @returns Date marker, e.g. `Date('2024-01-15T10:30:00Z')`
+ */
+declare function Date_(dateStr: string): `Date('${string}')`;
+/**
+ * Create a DateTime marker string. Same as Date on the server side.
+ *
+ * @param dateStr - ISO 8601 / RFC 3339 date string
+ * @returns DateTime marker, e.g. `DateTime('2024-01-15T10:30:00Z')`
+ */
+declare function DateTime(dateStr: string): `DateTime('${string}')`;
+/**
+ * Create a Timestamp marker string. The server converts this to a Unix timestamp.
+ *
+ * @param unix - Unix timestamp (seconds) as number or string
+ * @returns Timestamp marker, e.g. `Timestamp('1705312200')`
+ */
+declare function Timestamp(unix: number | string): `Timestamp('${string}')`;
+
+/**
+ * Create a Boolean marker. The server converts this to a Go bool.
+ */
+declare function Boolean_(val: boolean): `Boolean(${string})`;
+/**
+ * Create an Integer marker. The server converts this to int32.
+ */
+declare function Integer(n: number): `Integer(${number})`;
+/**
+ * Create a Bigint marker. The server converts this to int64.
+ */
+declare function Bigint(n: number | bigint): `Bigint(${number})`;
+/**
+ * Create a Float marker. The server converts this to float32.
+ */
+declare function Float(n: number): `Float(${number})`;
+/**
+ * Create a Double marker. The server converts this to float64.
+ */
+declare function Double(n: number): `Double(${number})`;
+
+/**
+ * Create an Array marker. The server converts this to a Go slice.
+ *
+ * @param arr - Array to serialize as JSON
+ */
+declare function Array_(arr: unknown[]): `Array(${string})`;
+/**
+ * Create a Map marker. The server converts this to a map[string]interface{}.
+ *
+ * @param obj - Object to serialize as JSON
+ */
+declare function Map_(obj: Record<string, unknown>): `Map(${string})`;
+/**
+ * Create a Map[] marker. The server converts this to []map[string]interface{}.
+ *
+ * @param arr - Array of objects to serialize as JSON
+ */
+declare function MapArray(arr: Record<string, unknown>[]): `Map[](${string})`;
+
+/**
+ * Null / null-equivalent markers that the server converts to Go nil.
+ *
+ * The server recognizes all these variants as null:
+ * 'Null', 'null', 'NULL', 'None', 'none', 'NONE', 'Nil', 'nil', 'NIL', '<nil>', ''
+ */
+/** Null marker — server converts to nil */
+declare const Null: "Null";
+/** None marker — server converts to nil */
+declare const None: "None";
+/** Nil marker — server converts to nil */
+declare const Nil: "Nil";
+/** empty string — server converts to nil (use '' directly) */
+declare const Empty: "";
+/**
+ * Undefined markers that the server converts to bson.Undefined{}.
+ */
+declare const UNDEFINED: "UNDEFINED";
+declare const Undefined: "Undefined";
+
+/**
+ * Time helper markers that the server evaluates at request time.
+ *
+ * These are string values that, when sent to the server, are replaced
+ * with the actual current time on the server side via Go's time.Now().
+ */
+/** Server fills in time.Now() (current UTC time) */
+declare const TimeNow: "time.Now()";
+/** Server fills in time.Now().Unix() (current Unix timestamp) */
+declare const TimeNowUnix: "time.Now().Unix()";
+/** Server fills in time.Now().UnixNano() */
+declare const TimeNowUnixNano: "time.Now().UnixNano()";
+/** Server fills in time.Now().Weekday() (e.g., time.Monday) */
+declare const TimeNowWeekday: "time.Now().Weekday()";
+/** Server fills in time.Now().Weekday().Chinese() (Chinese weekday name) */
+declare const TimeNowWeekdayChinese: "time.Now().Weekday().Chinese()";
+/**
+ * Convenience object grouping all time-now helpers.
+ *
+ * @example
+ * ```ts
+ * import { timeNow } from 't1y-sdk-js'
+ *
+ * await db.collection('posts').insertOne({
+ *   title: 'Hello',
+ *   createdAt: timeNow.Now(),
+ * })
+ * ```
+ */
+declare const timeNow: {
+    Now: () => "time.Now()";
+    NowUnix: () => "time.Now().Unix()";
+    NowUnixNano: () => "time.Now().UnixNano()";
+    NowWeekday: () => "time.Now().Weekday()";
+    NowWeekdayChinese: () => "time.Now().Weekday().Chinese()";
+};
+
+/**
+ * SHA-256 hashing — works in both Node.js and browser environments.
+ *
+ * Node.js (CJS): Uses node:crypto (synchronous via require)
+ * Node.js (ESM): Falls back to pure-JS (works correctly for all byte values)
+ * Browser: Uses pure-JS implementation
+ */
+/**
+ * Compute the SHA-256 hash of a string and return the hex digest.
+ *
+ * For the signing path: the input is always a UTF-8 string
+ * (method, URL, body JSON, etc.), so this works correctly.
+ *
+ * For raw binary data (from HMAC inner hash), use sha256RawBytesHex instead.
+ *
+ * @param data - Input string to hash (UTF-8)
+ * @returns Hex-encoded SHA-256 hash (64 hex characters)
+ */
+declare function sha256Hex(data: string): string;
+/**
+ * Compute SHA-256 hash asynchronously using Web Crypto API.
+ */
+declare function sha256HexAsync(data: string): Promise<string>;
+
+/**
+ * HMAC-SHA256 implementation — works in both Node.js and browser environments.
+ *
+ * Node.js (CJS): Uses node:crypto (synchronous via require)
+ * Browser / ESM: Uses pure-JS implementation operating on Uint8Array
+ */
+/**
+ * Compute HMAC-SHA256 and return hex digest.
+ *
+ * This is intentionally synchronous because it's called in the request
+ * signing path, which must be fast and cannot defer to async.
+ *
+ * @param secret - The secret key (raw string, used as-is as bytes)
+ * @param message - The message to sign
+ * @returns Hex-encoded HMAC-SHA256 signature (64 hex characters)
+ */
+declare function hmacSHA256Hex(secret: string, message: string): string;
+/**
+ * Compute HMAC-SHA256 asynchronously using Web Crypto API.
+ */
+declare function hmacSHA256HexAsync(secret: string, message: string): Promise<string>;
+/**
+ * Verify an HMAC-SHA256 signature using constant-time comparison.
+ */
+declare function verifyHmacSHA256(secret: string, message: string, signature: string): boolean;
+
+/**
+ * AES-256-GCM encryption and decryption.
+ *
+ * Compatible with the t1yOS Go server's AES-256-GCM implementation.
+ * Payload format: { "n": "<nonce base64>", "j": "<ciphertext base64>", "t": "<tag base64>" }
+ *
+ * Works in both Node.js and browser via Web Crypto API.
+ */
+/**
+ * AES-256-GCM encrypted payload structure.
+ * Matches the Go server's AESGCMEncryptedPayload struct.
+ */
+interface AESGCMPayload {
+    /** Base64-encoded nonce */
+    n: string;
+    /** Base64-encoded ciphertext */
+    j: string;
+    /** Base64-encoded authentication tag */
+    t: string;
+}
+/**
+ * Encrypt data using AES-256-GCM.
+ *
+ * @param data - The plaintext data to encrypt (string)
+ * @param keyBytes - 32-byte encryption key (Uint8Array)
+ * @returns JSON string of { n, j, t } payload
+ */
+declare function encryptAESGCM(data: string, keyBytes: Uint8Array): Promise<string>;
+/**
+ * Decrypt data using AES-256-GCM.
+ *
+ * @param jsonPayload - JSON string of { n, j, t } payload
+ * @param keyBytes - 32-byte decryption key (Uint8Array)
+ * @returns Decrypted plaintext string
+ */
+declare function decryptAESGCM(jsonPayload: string, keyBytes: Uint8Array): Promise<string>;
+
+/**
+ * Request signing algorithm for T1Y v5 RESTful API authentication.
+ *
+ * Implements the same signing logic as the Go server's middleware/v5_auth.go:
+ *
+ *   message   = METHOD + "\n" + URL_PATH_AND_QUERY + "\n" + SHA256(body) + "\n" + appId + "\n" + timestamp
+ *   signature = HMAC-SHA256(secretKey, message)
+ */
+/**
+ * Parameters for creating a request signature.
+ */
+interface SignatureInput {
+    /** HTTP method in uppercase (GET, POST, PUT, DELETE) */
+    method: string;
+    /** URL path including query string, e.g. /v5/classes/users?field=name */
+    pathAndQuery: string;
+    /** Request body as a raw string (empty string for GET requests) */
+    body: string;
+    /** Application ID */
+    appId: number;
+    /** 10-digit Unix timestamp (UTC + offset) */
+    timestamp: number;
+    /** 32-character Secret Key */
+    secretKey: string;
+}
+/**
+ * Create an HMAC-SHA256 signature for a T1Y API request.
+ *
+ * The message format is (each line separated by \n):
+ *   1. HTTP method (uppercase)
+ *   2. URL path + query string
+ *   3. SHA-256 hex digest of the request body
+ *   4. Application ID (as string)
+ *   5. Unix timestamp (as string)
+ *
+ * @param input - Signature parameters
+ * @returns 64-character hex-encoded HMAC-SHA256 signature
+ *
+ * @example
+ * ```ts
+ * const sign = createSignature({
+ *   method: 'POST',
+ *   pathAndQuery: '/v5/classes/users',
+ *   body: '{"name":"Alice"}',
+ *   appId: 1001,
+ *   timestamp: 1705312200,
+ *   secretKey: '17b784e359c946ffa65eebbf9ce29752',
+ * })
+ * // Set as X-T1Y-Safe-Sign header
+ * ```
+ */
+declare function createSignature(input: SignatureInput): string;
+/**
+ * Get the current UTC Unix timestamp adjusted by the given offset.
+ *
+ * @param offset - Time offset in seconds (from server init)
+ * @returns 10-digit Unix timestamp string
+ */
+declare function getSafeTimestamp(offset: number): string;
+
+/**
+ * Custom error class for t1yOS SDK errors.
+ * Wraps API error responses with code, message, and data.
+ */
+declare class T1YError extends Error {
+    /** HTTP status or error code */
+    code: number;
+    /** Response data from server (if any) */
+    data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Validation error thrown when configuration parameters are invalid.
+ */
+declare class ValidationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Validate that the application ID is a valid integer >= MIN_APP_ID.
+ */
+declare function validateAppId(appId: number): void;
+/**
+ * Validate that the API Key is exactly the required length.
+ */
+declare function validateApiKey(apiKey: string): void;
+/**
+ * Validate that the Secret Key is exactly the required length.
+ */
+declare function validateSecretKey(secretKey: string): void;
+/**
+ * Validate the base URL format.
+ */
+declare function validateBaseUrl(baseUrl: string): void;
+/**
+ * Validate all configuration parameters at once.
+ */
+declare function validateInitConfig(config: T1YOSConfig): void;
+/**
+ * Validate an ObjectID hex string.
+ * Returns true if valid, throws otherwise.
+ */
+declare function assertObjectID(idStr: string, name?: string): boolean;
+
+/**
+ * Recursively convert JavaScript Date objects and timestamp numbers
+ * into the marker string format that the server's GetDataTypes() recognizes.
+ *
+ * - Date objects → `Date('ISO-8601')`
+ * - Numbers >= 10 digits → `Timestamp('unix')`
+ * - Already-marker strings (starting with recognized prefixes) are passed through
+ */
+declare function convertDateTypes(value: unknown): unknown;
+/**
+ * Check if a value is a non-null, non-array object with at least one key.
+ */
+declare function isNonEmptyObject(value: unknown): boolean;
+/**
+ * Check if a value is a plain object (non-null, non-array).
+ */
+declare function isPlainObject(value: unknown): boolean;
+/**
+ * Check if a value is a non-empty array where every element is a non-empty object.
+ */
+declare function isNonEmptyArrayWithNonEmptyObjects(value: unknown): boolean;
+
+/**
+ * Recursively convert all `createdAt` and `updatedAt` fields in a data structure
+ * from UTC strings to local time formatted strings.
+ *
+ * Returns a new object/array; does not mutate the original.
+ */
+declare function formatTimestampsToLocal(data: unknown, format?: string): unknown;
+
+export { type AESGCMPayload, type AggregateResult, type ApiResponse, Array_ as Array, type ArrayMarker, Bigint, type BigintMarker, Boolean_ as Boolean, type BooleanMarker, Date_ as Date, type DateMarker, DateTime, type DateTimeMarker, type DeleteManyResult, type DeleteResult, Double, type DoubleMarker, Empty, type FindResult, Float, type FloatMarker, type HttpMethod, type InitResult, type InsertManyResult, type InsertResult, Integer, type IntegerMarker, Map_ as Map, MapArray, type MapArrayMarker, type MapMarker, Nil, None, Null, type NullMarker, ObjectID, type ObjectIDMarker, type Pagination, type PaginationResult, type SignatureInput, type SpecialTypeMarker, T1Collection, T1YError, T1YOS, type T1YOSConfig, type T1YOSInternalConfig, TimeNow, type TimeNowMarker, TimeNowUnix, type TimeNowUnixMarker, TimeNowUnixNano, type TimeNowUnixNanoMarker, TimeNowWeekday, TimeNowWeekdayChinese, type TimeNowWeekdayChineseMarker, type TimeNowWeekdayMarker, Timestamp, type TimestampMarker, UNDEFINED, Undefined, type UndefinedMarker, type UpdateManyResult, type UpdateResult, ValidationError, assertObjectID, convertDateTypes, createSignature, decryptAESGCM, T1YOS as default, encryptAESGCM, formatTimestampsToLocal, getSafeTimestamp, hmacSHA256Hex, hmacSHA256HexAsync, isNonEmptyArrayWithNonEmptyObjects, isNonEmptyObject, isPlainObject, sha256Hex, sha256HexAsync, timeNow, validateApiKey, validateAppId, validateBaseUrl, validateInitConfig, validateSecretKey, verifyHmacSHA256 };