@ariadng/sheets 0.4.0 → 0.4.2

package/dist/index.d.ts

@@ -1,11 +1,356 @@
 /**
- * @ariadng/google-sheets
- * Google Sheets API interface and CLI tool
- */
-export { SheetsClient, createClient } from './api/index.js';
-export { createAuthProvider, OAuthAuth, ServiceAccountAuth, UserAuth, login, loadStoredTokens, deleteTokens } from './auth/index.js';
-export type { AuthProvider } from './auth/index.js';
-export { HttpClient } from './http/index.js';
-export type { GridProperties, SheetProperties, Spreadsheet, SpreadsheetProperties, CellValue, CellFormat, Color, TextFormat, ValueRange, GetValuesOptions, BatchGetValuesResponse, ClearValuesResponse, BatchClearValuesResponse, ValueRenderOption, DateTimeRenderOption, MajorDimension, ValueInputOption, InsertDataOption, RawCellValue, UpdateValuesOptions, AppendValuesOptions, UpdateValuesResponse, BatchUpdateValuesResponse, AppendValuesResponse, SearchMatch, SearchOptions, SearchResult, AuthConfig, OAuthConfig, ServiceAccountConfig, ServiceAccountCredentials, UserAuthConfig, StoredTokens, SheetsClientOptions, SheetsApiError, SheetsApiErrorDetail, } from './types/index.js';
-export { SheetsError } from './types/index.js';
-//# sourceMappingURL=index.d.ts.map
+ * Google Sheets API Type Definitions
+ */
+interface GridProperties {
+    rowCount: number;
+    columnCount: number;
+    frozenRowCount?: number;
+    frozenColumnCount?: number;
+    hideGridlines?: boolean;
+}
+interface SheetProperties {
+    sheetId: number;
+    title: string;
+    index: number;
+    sheetType?: 'GRID' | 'OBJECT' | 'DATA_SOURCE';
+    gridProperties?: GridProperties;
+    hidden?: boolean;
+    rightToLeft?: boolean;
+}
+interface SpreadsheetProperties {
+    title: string;
+    locale?: string;
+    timeZone?: string;
+    autoRecalc?: 'ON_CHANGE' | 'MINUTE' | 'HOUR';
+    defaultFormat?: CellFormat;
+}
+interface Spreadsheet {
+    spreadsheetId: string;
+    properties: SpreadsheetProperties;
+    sheets: {
+        properties: SheetProperties;
+    }[];
+    spreadsheetUrl?: string;
+}
+interface CellFormat {
+    numberFormat?: {
+        type: string;
+        pattern?: string;
+    };
+    backgroundColor?: Color;
+    textFormat?: TextFormat;
+}
+interface Color {
+    red?: number;
+    green?: number;
+    blue?: number;
+    alpha?: number;
+}
+interface TextFormat {
+    foregroundColor?: Color;
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+    underline?: boolean;
+}
+interface CellValue {
+    value: string | number | boolean | null;
+    formula?: string;
+    formattedValue?: string;
+}
+type ValueRenderOption = 'FORMATTED_VALUE' | 'UNFORMATTED_VALUE' | 'FORMULA';
+type DateTimeRenderOption = 'SERIAL_NUMBER' | 'FORMATTED_STRING';
+type MajorDimension = 'ROWS' | 'COLUMNS';
+interface ValueRange {
+    range: string;
+    majorDimension: MajorDimension;
+    values: CellValue[][];
+}
+interface GetValuesOptions {
+    valueRenderOption?: ValueRenderOption;
+    dateTimeRenderOption?: DateTimeRenderOption;
+    majorDimension?: MajorDimension;
+}
+interface BatchGetValuesResponse {
+    spreadsheetId: string;
+    valueRanges: ValueRange[];
+}
+interface ClearValuesResponse {
+    spreadsheetId: string;
+    clearedRange: string;
+}
+interface BatchClearValuesResponse {
+    spreadsheetId: string;
+    clearedRanges: string[];
+}
+type ValueInputOption = 'RAW' | 'USER_ENTERED';
+type InsertDataOption = 'OVERWRITE' | 'INSERT_ROWS';
+type RawCellValue = string | number | boolean | null;
+interface UpdateValuesOptions {
+    valueInputOption?: ValueInputOption;
+    majorDimension?: MajorDimension;
+    includeValuesInResponse?: boolean;
+    responseValueRenderOption?: ValueRenderOption;
+    responseDateTimeRenderOption?: DateTimeRenderOption;
+}
+interface AppendValuesOptions extends UpdateValuesOptions {
+    insertDataOption?: InsertDataOption;
+}
+interface UpdateValuesResponse {
+    spreadsheetId: string;
+    updatedRange: string;
+    updatedRows: number;
+    updatedColumns: number;
+    updatedCells: number;
+    updatedData?: ValueRange;
+}
+interface BatchUpdateValuesResponse {
+    spreadsheetId: string;
+    totalUpdatedRows: number;
+    totalUpdatedColumns: number;
+    totalUpdatedCells: number;
+    totalUpdatedSheets: number;
+    responses: UpdateValuesResponse[];
+}
+interface AppendValuesResponse {
+    spreadsheetId: string;
+    tableRange?: string;
+    updates: UpdateValuesResponse;
+}
+interface SearchMatch {
+    sheet: string;
+    sheetId: number;
+    address: string;
+    row: number;
+    column: number;
+    value: string | number | boolean | null;
+}
+interface SearchOptions {
+    range?: string;
+    sheetIndex?: number;
+    gid?: number;
+    caseSensitive?: boolean;
+    exactMatch?: boolean;
+    regex?: boolean;
+    limit?: number;
+}
+interface SearchResult {
+    query: string;
+    matchType: 'contains' | 'exact' | 'regex';
+    caseSensitive: boolean;
+    totalMatches: number;
+    matches: SearchMatch[];
+}
+interface OAuthConfig {
+    type: 'oauth';
+    accessToken: string;
+    refreshToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+    expiresAt?: number;
+}
+interface ServiceAccountConfig {
+    type: 'service-account';
+    credentialsPath?: string;
+    credentials?: ServiceAccountCredentials;
+}
+interface ServiceAccountCredentials {
+    type: 'service_account';
+    project_id: string;
+    private_key_id: string;
+    private_key: string;
+    client_email: string;
+    client_id: string;
+    auth_uri: string;
+    token_uri: string;
+}
+interface UserAuthConfig {
+    type: 'user';
+}
+interface StoredTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    email?: string;
+}
+type AuthConfig = OAuthConfig | ServiceAccountConfig | UserAuthConfig;
+interface SheetsClientOptions {
+    auth: AuthConfig;
+}
+interface SheetsApiErrorDetail {
+    '@type'?: string;
+    reason?: string;
+    domain?: string;
+    metadata?: Record<string, string>;
+}
+interface SheetsApiError {
+    code: number;
+    message: string;
+    status: string;
+    details?: SheetsApiErrorDetail[];
+}
+declare class SheetsError extends Error {
+    code: number;
+    status: string;
+    details?: SheetsApiErrorDetail[];
+    constructor(error: SheetsApiError);
+}
+
+/**
+ * Google Sheets API Client
+ */
+
+declare class SheetsClient {
+    private http;
+    constructor(options: SheetsClientOptions);
+    /**
+     * Get a spreadsheet by ID
+     */
+    getSpreadsheet(spreadsheetId: string): Promise<Spreadsheet>;
+    /**
+     * Get list of sheets in a spreadsheet
+     */
+    getSheets(spreadsheetId: string): Promise<SheetProperties[]>;
+    /**
+     * Read cell values from a range
+     */
+    getValues(spreadsheetId: string, range: string, options?: GetValuesOptions): Promise<ValueRange>;
+    /**
+     * Read cell formulas from a range
+     */
+    getFormulas(spreadsheetId: string, range: string): Promise<ValueRange>;
+    /**
+     * Read multiple ranges at once
+     */
+    batchGetValues(spreadsheetId: string, ranges: string[], options?: GetValuesOptions): Promise<BatchGetValuesResponse>;
+    /**
+     * Clear values from a single range
+     */
+    clearValues(spreadsheetId: string, range: string): Promise<ClearValuesResponse>;
+    /**
+     * Clear values from multiple ranges
+     */
+    batchClearValues(spreadsheetId: string, ranges: string[]): Promise<BatchClearValuesResponse>;
+    /**
+     * Write values to a range (or starting cell)
+     * Range can be "A1" or "A1:D10" - data array determines actual extent
+     */
+    updateValues(spreadsheetId: string, range: string, values: RawCellValue[][], options?: UpdateValuesOptions): Promise<UpdateValuesResponse>;
+    /**
+     * Write to multiple ranges in one request
+     */
+    batchUpdateValues(spreadsheetId: string, data: {
+        range: string;
+        values: RawCellValue[][];
+    }[], options?: UpdateValuesOptions): Promise<BatchUpdateValuesResponse>;
+    /**
+     * Append rows after the last row of detected table
+     */
+    appendValues(spreadsheetId: string, range: string, values: RawCellValue[][], options?: AppendValuesOptions): Promise<AppendValuesResponse>;
+    /**
+     * Search for values matching a query across sheets
+     */
+    searchValues(spreadsheetId: string, query: string, options?: SearchOptions): Promise<SearchResult>;
+    private collectMatches;
+    private normalizeValueRange;
+}
+declare function createClient(options: SheetsClientOptions): SheetsClient;
+
+/**
+ * OAuth 2.0 Authentication
+ * Supports pre-obtained access tokens with optional auto-refresh
+ *
+ * For automation (e.g., n8n), provide:
+ * - accessToken: Current access token
+ * - refreshToken: For obtaining new tokens when expired
+ * - clientId: OAuth client ID
+ * - clientSecret: OAuth client secret
+ * - expiresAt: When the access token expires (Unix timestamp in ms)
+ */
+
+declare class OAuthAuth {
+    private config;
+    private cachedToken;
+    private expiresAt;
+    constructor(config: OAuthConfig);
+    getAccessToken(): Promise<string>;
+    private canRefresh;
+    private isExpired;
+    private refreshToken;
+    /**
+     * Get current token state for persistence in automation tools
+     * Returns updated tokens after any refresh operations
+     */
+    getTokenState(): {
+        accessToken: string;
+        refreshToken?: string;
+        expiresAt: number;
+    };
+}
+
+/**
+ * Service Account JWT Authentication
+ * Uses RS256 signing to exchange JWT for access token
+ */
+
+declare class ServiceAccountAuth {
+    private config;
+    private credentials;
+    private cachedToken;
+    private tokenExpiresAt;
+    constructor(config: ServiceAccountConfig);
+    getAccessToken(): Promise<string>;
+    private loadCredentials;
+    private createJwt;
+    private base64UrlEncode;
+    private exchangeJwtForToken;
+}
+
+/**
+ * User OAuth Authentication
+ * OAuth 2.0 Authorization Code flow with PKCE for personal Google accounts
+ */
+
+interface OAuthClientCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+declare function loadStoredTokens(): Promise<StoredTokens | null>;
+declare function deleteTokens(): Promise<void>;
+declare function login(credentials?: OAuthClientCredentials): Promise<StoredTokens>;
+declare class UserAuth {
+    private tokens;
+    getAccessToken(): Promise<string>;
+}
+
+/**
+ * Authentication Module Exports
+ */
+
+interface AuthProvider {
+    getAccessToken(): Promise<string>;
+}
+declare function createAuthProvider(config: AuthConfig): AuthProvider;
+
+/**
+ * HTTP Client for Google Sheets API
+ * Uses native Node.js fetch (Node 18+)
+ */
+interface HttpClientOptions {
+    getAccessToken: () => Promise<string>;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: unknown;
+    params?: Record<string, string>;
+}
+declare class HttpClient {
+    private getAccessToken;
+    constructor(options: HttpClientOptions);
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    private sleep;
+}
+
+export { type AppendValuesOptions, type AppendValuesResponse, type AuthConfig, type AuthProvider, type BatchClearValuesResponse, type BatchGetValuesResponse, type BatchUpdateValuesResponse, type CellFormat, type CellValue, type ClearValuesResponse, type Color, type DateTimeRenderOption, type GetValuesOptions, type GridProperties, HttpClient, type InsertDataOption, type MajorDimension, OAuthAuth, type OAuthConfig, type RawCellValue, type SearchMatch, type SearchOptions, type SearchResult, ServiceAccountAuth, type ServiceAccountConfig, type ServiceAccountCredentials, type SheetProperties, type SheetsApiError, type SheetsApiErrorDetail, SheetsClient, type SheetsClientOptions, SheetsError, type Spreadsheet, type SpreadsheetProperties, type StoredTokens, type TextFormat, type UpdateValuesOptions, type UpdateValuesResponse, UserAuth, type UserAuthConfig, type ValueInputOption, type ValueRange, type ValueRenderOption, createAuthProvider, createClient, deleteTokens, loadStoredTokens, login };