@salesforce/b2c-tooling-sdk 0.4.1 → 0.5.0

package/dist/esm/clients/cip.d.ts

@@ -0,0 +1,162 @@
+import type { AuthStrategy } from '../auth/types.js';
+import { type MiddlewareRegistry } from './middleware-registry.js';
+/** Default CIP Avatica host. */
+export declare const DEFAULT_CIP_HOST = "jdbc.analytics.commercecloud.salesforce.com";
+/** Default CIP Avatica host for staging/non-production analytics. */
+export declare const DEFAULT_CIP_STAGING_HOST = "jdbc.stg.analytics.commercecloud.salesforce.com";
+/** CIP client configuration. */
+export interface CipClientConfig {
+    /** CIP instance identifier (for example `zzxy_prd`). */
+    instance: string;
+    /** Optional CIP host override. */
+    host?: string;
+    /** Middleware registry to use for this client. Defaults to global registry. */
+    middlewareRegistry?: MiddlewareRegistry;
+}
+/** Column metadata for a CIP result set. */
+export interface CipColumn {
+    /** Preferred output label for the column. */
+    label: string;
+    /** Original column name, when provided by CIP. */
+    name?: string;
+    /** Avatica type name (for example `VARCHAR`, `DATE`). */
+    typeName?: string;
+}
+/** Decoded CIP frame. */
+export interface CipFrame {
+    /** Row offset in the full result set. */
+    offset: number;
+    /** Whether this is the terminal frame. */
+    done: boolean;
+    /** Column metadata for row decoding. */
+    columns: CipColumn[];
+    /** Decoded row objects. */
+    rows: Array<Record<string, unknown>>;
+}
+/** Execute response with decoded first frame. */
+export interface CipExecuteResponse {
+    /** Statement id used for this execution. */
+    statementId: number;
+    /** Decoded first frame when present. */
+    frame?: CipFrame;
+}
+/** Fetch response with decoded frame. */
+export interface CipFetchResponse {
+    /** Decoded fetched frame when present. */
+    frame?: CipFrame;
+}
+/** Convenience result for full query execution. */
+export interface CipQueryResult {
+    /** Ordered columns for output formatting. */
+    columns: string[];
+    /** Decoded result rows. */
+    rows: Array<Record<string, unknown>>;
+    /** Total number of rows returned. */
+    rowCount: number;
+}
+/** Options for high-level query execution. */
+export interface CipQueryOptions {
+    /** Initial and subsequent frame fetch size. */
+    fetchSize?: number;
+    /** Optional Avatica connection properties. */
+    connectionProperties?: Record<string, string>;
+}
+/**
+ * CIP Avatica client with protobuf transport.
+ *
+ * Use this client for raw SQL execution against B2C Commerce Intelligence
+ * (CIP/CCAC) data.
+ *
+ * See {@link createCipClient} for the recommended construction helper.
+ *
+ * @example
+ * ```ts
+ * import {OAuthStrategy} from '@salesforce/b2c-tooling-sdk/auth';
+ * import {createCipClient} from '@salesforce/b2c-tooling-sdk/clients';
+ *
+ * const auth = new OAuthStrategy({
+ *   clientId: process.env.SFCC_CLIENT_ID!,
+ *   clientSecret: process.env.SFCC_CLIENT_SECRET!,
+ * });
+ *
+ * const cip = createCipClient({instance: 'zzxy_prd'}, auth);
+ *
+ * const result = await cip.query(
+ *   'SELECT submit_date, num_orders FROM ccdw_aggr_sales_summary LIMIT 10',
+ *   {fetchSize: 500},
+ * );
+ *
+ * console.log(result.rowCount, result.columns, result.rows[0]);
+ * ```
+ */
+export declare class CipClient {
+    private readonly config;
+    private readonly auth;
+    private readonly baseUrl;
+    private readonly middlewareRegistry;
+    private protoRoot?;
+    private connectionId?;
+    private sessionId?;
+    private readonly signatureByStatementId;
+    constructor(config: CipClientConfig, auth: AuthStrategy);
+    /**
+     * Opens a new Avatica connection.
+     */
+    openConnection(info?: Record<string, string>): Promise<void>;
+    /**
+     * Closes the current Avatica connection (no-op if not open).
+     */
+    closeConnection(): Promise<void>;
+    /**
+     * Creates a statement in the currently open connection.
+     */
+    createStatement(): Promise<number>;
+    /**
+     * Closes a statement.
+     */
+    closeStatement(statementId: number): Promise<void>;
+    /**
+     * Executes SQL and returns the first decoded frame.
+     */
+    execute(statementId: number, sql: string, firstFrameMaxSize?: number): Promise<CipExecuteResponse>;
+    /**
+     * Fetches an additional frame for an existing statement.
+     */
+    fetch(statementId: number, offset: number, fetchMaxRowCount?: number): Promise<CipFetchResponse>;
+    /**
+     * Executes SQL and returns the full decoded row set.
+     *
+     * This helper opens and closes the connection automatically.
+     */
+    query(sql: string, options?: CipQueryOptions): Promise<CipQueryResult>;
+    private requireConnection;
+    private getMiddleware;
+    private getProtoRoot;
+    private sendRequest;
+    private decodeFrame;
+    private getColumnsFromSignature;
+    private getColumnTypeName;
+    private decodeColumnValue;
+    private decodeTypedValue;
+    private decodeNumericValue;
+    private formatProtobufBody;
+    private headersToObject;
+}
+/**
+ * Creates a CIP client and ensures the required CIP scope on OAuth strategies.
+ *
+ * @example
+ * ```ts
+ * import {OAuthStrategy} from '@salesforce/b2c-tooling-sdk/auth';
+ * import {createCipClient} from '@salesforce/b2c-tooling-sdk/clients';
+ *
+ * const auth = new OAuthStrategy({
+ *   clientId: process.env.SFCC_CLIENT_ID!,
+ *   clientSecret: process.env.SFCC_CLIENT_SECRET!,
+ * });
+ *
+ * const cip = createCipClient({instance: 'zzxy_prd'}, auth);
+ * const query = await cip.query('SELECT submit_date FROM ccdw_aggr_sales_summary LIMIT 1');
+ * ```
+ */
+export declare function createCipClient(config: CipClientConfig, auth: AuthStrategy): CipClient;