@rnsk/toolkits 0.0.8 → 0.0.10

package/dist/toolkits/google-analytics/tools/reports.js

@@ -0,0 +1,200 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { DATA_V1ALPHA, DATA_V1BETA, gaList, gaPost, gaRequest, googleAnalyticsTokenField, namedDimension, namedMetric, normalizeProperty, paginationSchema, } from './client.js';
+const dateRange = z
+    .object({
+    startDate: z.string().describe("Start date 'YYYY-MM-DD', 'today', 'yesterday', or 'NdaysAgo'"),
+    endDate: z.string().describe("End date 'YYYY-MM-DD', 'today', 'yesterday', or 'NdaysAgo'"),
+    name: z.string().optional(),
+})
+    .catchall(z.unknown());
+const reportBody = {
+    dateRanges: z.array(dateRange).optional().describe('Date ranges (one required for most reports)'),
+    dimensions: z.array(namedDimension).optional().describe("Dimensions, e.g. [{name:'country'}] — confirm apiNames via getMetadata"),
+    metrics: z.array(namedMetric).optional().describe("Metrics, e.g. [{name:'activeUsers'}] (max 10) — confirm apiNames via getMetadata"),
+    dimensionFilter: z.record(z.any()).optional().describe('Dimension filter expression'),
+    metricFilter: z.record(z.any()).optional().describe('Metric filter expression'),
+    orderBys: z.array(z.record(z.any())).optional().describe("Ordering, e.g. [{desc:true,metric:{metricName:'activeUsers'}}]"),
+    limit: z.number().min(1).max(250000).optional().describe('Rows to return'),
+    offset: z.number().min(0).optional().describe('0-based start row for pagination'),
+    currencyCode: z.string().optional().describe("ISO 4217 currency, e.g. 'USD'"),
+    cohortSpec: z.record(z.any()).optional(),
+    comparisons: z.array(z.record(z.any())).optional(),
+    keepEmptyRows: z.boolean().optional(),
+    returnPropertyQuota: z.boolean().optional().describe('Include quota state in response'),
+};
+function reportExecute(base, suffix, action, extraBody) {
+    return async ({ googleAnalyticsToken, property, ...body }) => {
+        const payload = {};
+        for (const [k, v] of Object.entries(body))
+            if (v !== undefined)
+                payload[k] = v;
+        extraBody?.(payload);
+        return gaPost(googleAnalyticsToken, base, `${normalizeProperty(property)}:${suffix}`, payload, undefined, action);
+    };
+}
+const propertyField = z.string().describe("GA4 property 'properties/{id}' (bare numeric ID accepted)");
+export const runReport = tool({
+    description: 'Runs a standard GA4 report (dimensions × metrics over date ranges). Confirm dimension/metric apiNames via getMetadata first; check compatibility for risky combos.',
+    inputSchema: z.object({ googleAnalyticsToken: googleAnalyticsTokenField, property: propertyField, ...reportBody, metricAggregations: z.array(z.string()).optional() }),
+    execute: reportExecute(DATA_V1BETA, 'runReport', 'run report'),
+});
+export const batchRunReports = tool({
+    description: 'Runs multiple standard reports for one property in a single call. Each entry is a full runReport-style request.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        property: propertyField,
+        requests: z.array(z.record(z.any())).min(1).describe('Report requests (runReport bodies without property)'),
+    }),
+    execute: reportExecute(DATA_V1BETA, 'batchRunReports', 'batch run reports', (payload) => {
+        const { requests } = payload;
+        delete payload.requests;
+        payload.requests = requests;
+    }),
+});
+export const runPivotReport = tool({
+    description: 'Runs a pivot-table report (multi-dimensional cross-tab). Define pivots with fieldNames, limit, and metricAggregations.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        property: propertyField,
+        metrics: z.array(namedMetric).min(1).describe('At least one metric is required'),
+        pivots: z.array(z.record(z.any())).optional().describe("Pivots, e.g. [{fieldNames:['country'],limit:10}]"),
+        ...reportBody,
+    }),
+    execute: reportExecute(DATA_V1BETA, 'runPivotReport', 'run pivot report'),
+});
+export const batchRunPivotReports = tool({
+    description: 'Runs multiple pivot reports for one property in a single call.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        property: propertyField,
+        requests: z.array(z.record(z.any())).min(1).describe('Pivot report requests (runPivotReport bodies without property)'),
+    }),
+    execute: reportExecute(DATA_V1BETA, 'batchRunPivotReports', 'batch run pivot reports'),
+});
+export const runRealtimeReport = tool({
+    description: 'Runs a realtime report (last 30 minutes of activity). No date ranges; use minuteRanges and metricAggregations instead.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        property: propertyField,
+        dimensions: z.array(namedDimension).optional(),
+        metrics: z.array(namedMetric).optional(),
+        dimensionFilter: z.record(z.any()).optional(),
+        metricFilter: z.record(z.any()).optional(),
+        orderBys: z.array(z.record(z.any())).optional(),
+        limit: z.number().min(1).optional(),
+        minuteRanges: z.array(z.record(z.any())).optional().describe("Minute ranges, e.g. [{startMinutesAgo:29,endMinutesAgo:0}]"),
+        metricAggregations: z.array(z.string()).optional(),
+        returnPropertyQuota: z.boolean().optional(),
+    }),
+    execute: reportExecute(DATA_V1BETA, 'runRealtimeReport', 'run realtime report'),
+});
+export const runFunnelReport = tool({
+    description: 'Runs a funnel analysis report. Funnel needs steps[{name, filterExpression}]; step order in the response comes from step attributes, not row order.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        property: propertyField,
+        funnel: z.record(z.any()).describe("Funnel config with 'steps' (each step: name + filterExpression using funnelEventFilter/funnelFieldFilter)"),
+        dateRanges: z.array(dateRange).optional(),
+        segments: z.array(z.record(z.any())).max(4).optional().describe('Up to 4 segments, each yields its own row'),
+        dimensionFilter: z.record(z.any()).optional(),
+        funnelBreakdown: z.record(z.any()).optional(),
+        funnelNextAction: z.record(z.any()).optional(),
+        funnelVisualizationType: z.string().optional(),
+        limit: z.number().min(1).max(250000).optional(),
+        returnPropertyQuota: z.boolean().optional(),
+    }),
+    execute: reportExecute(DATA_V1BETA, 'runFunnelReport', 'run funnel report'),
+});
+export const checkCompatibility = tool({
+    description: 'Lists dimensions/metrics compatible with a report request. Call before runReport when mixing custom or unusual fields.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        property: propertyField,
+        dimensions: z.array(namedDimension).optional(),
+        metrics: z.array(namedMetric).max(10).optional().describe('Max 10 metrics'),
+        dimensionFilter: z.record(z.any()).optional(),
+        metricFilter: z.record(z.any()).optional(),
+        compatibilityFilter: z.enum(['DIMENSION_COMPATIBILITY_FILTER_UNSPECIFIED', 'COMPATIBLE', 'INCOMPATIBLE']).optional(),
+    }),
+    execute: reportExecute(DATA_V1BETA, 'checkCompatibility', 'check compatibility'),
+});
+export const getMetadata = tool({
+    description: 'Gets report metadata (available dimensions, metrics, comparisons) for a property. Always derive apiNames from here instead of hardcoding.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        name: z.string().describe("Metadata name 'properties/{id}/metadata' (bare ID accepted)"),
+    }),
+    execute: async ({ googleAnalyticsToken, name }) => {
+        try {
+            const full = name.includes('/metadata') ? name : `${normalizeProperty(name)}/metadata`;
+            const result = await gaRequest(googleAnalyticsToken, DATA_V1BETA, `/${full}`);
+            if (!result.ok)
+                return { error: 'Failed to get metadata', details: result.error };
+            return result.data;
+        }
+        catch (error) {
+            return { error: 'Error getting metadata', message: error instanceof Error ? error.message : 'Unknown error' };
+        }
+    },
+});
+export const createReportTask = tool({
+    description: 'Creates an async report task for large/complex event-data reports. Poll getReportTask until ACTIVE, then queryReportTask for rows.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        parent: z.string().describe("Property 'properties/{id}' (bare ID accepted)"),
+        reportDefinition: z.record(z.any()).optional().describe('Report definition (metrics, dimensions, dateRanges, limit up to 250000)'),
+    }),
+    execute: async ({ googleAnalyticsToken, parent, reportDefinition }) => {
+        const body = {};
+        if (reportDefinition)
+            body.reportDefinition = reportDefinition;
+        return gaPost(googleAnalyticsToken, DATA_V1ALPHA, `${normalizeProperty(parent)}/reportTasks`, body, undefined, 'create report task');
+    },
+});
+export const getReportTask = tool({
+    description: 'Gets report-task metadata (processing state, definition). Use after createReportTask to check readiness.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        name: z.string().describe("Report task 'properties/{id}/reportTasks/{taskId}'"),
+    }),
+    execute: async ({ googleAnalyticsToken, name }) => {
+        try {
+            const result = await gaRequest(googleAnalyticsToken, DATA_V1ALPHA, `/${name}`);
+            if (!result.ok)
+                return { error: 'Failed to get report task', details: result.error };
+            return result.data;
+        }
+        catch (error) {
+            return { error: 'Error getting report task', message: error instanceof Error ? error.message : 'Unknown error' };
+        }
+    },
+});
+export const listReportTasks = tool({
+    description: 'Lists report tasks for a property to find and reuse existing tasks.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        parent: z.string().describe("Property 'properties/{id}' (bare ID accepted)"),
+        ...paginationSchema,
+    }),
+    execute: async ({ googleAnalyticsToken, parent, pageSize, pageToken }) => gaList(googleAnalyticsToken, DATA_V1ALPHA, normalizeProperty(parent), 'reportTasks', { pageSize, pageToken }, 'list report tasks'),
+});
+export const queryReportTask = tool({
+    description: 'Retrieves rows from an ACTIVE report task. Errors unless the task state is ACTIVE — check getReportTask first.',
+    inputSchema: z.object({
+        googleAnalyticsToken: googleAnalyticsTokenField,
+        name: z.string().describe("Report task 'properties/{id}/reportTasks/{taskId}'"),
+        limit: z.number().min(1).max(250000).optional().describe('Rows to return (default 10000, capped by task limit)'),
+        offset: z.number().min(0).optional().describe('0-based row offset; omit or 0 for first page'),
+    }),
+    execute: async ({ googleAnalyticsToken, name, limit, offset }) => {
+        const body = {};
+        if (limit !== undefined)
+            body.limit = limit;
+        if (offset !== undefined)
+            body.offset = offset;
+        return gaPost(googleAnalyticsToken, DATA_V1ALPHA, `${name}:query`, body, undefined, 'query report task');
+    },
+});
+//# sourceMappingURL=reports.js.map

package/dist/toolkits/google-contacts/icon.d.ts

@@ -0,0 +1,5 @@
+export declare const GCONTACTS_ICON: {
+    kind: "svg";
+    dataUri: string;
+};
+//# sourceMappingURL=icon.d.ts.map

package/dist/toolkits/google-contacts/icon.js

@@ -0,0 +1,6 @@
+const SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 500"><path fill="#86a9ff" d="M199 244c-89 0-161 71-161 160v67c0 16 13 29 29 29h77l77-256z"/><path fill="#578cff" d="M462 349c0-58-48-105-106-105h-77v256h77c58 0 106-47 106-106"/><path fill="#0057cc" d="M115 349c0-58 48-105 106-105h58c58 0 106 47 106 105v45c0 59-48 106-106 106H144c-16 0-29-13-29-29z"/><circle cx="250" cy="99.4" r="99.4" fill="#0057cc"/></svg>`;
+export const GCONTACTS_ICON = {
+    kind: 'svg',
+    dataUri: `data:image/svg+xml;base64,${Buffer.from(SVG).toString('base64')}`,
+};
+//# sourceMappingURL=icon.js.map

package/dist/toolkits/google-contacts/manifest.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("../../index.js").ToolkitManifest;
+export default _default;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/toolkits/google-contacts/manifest.js

@@ -0,0 +1,48 @@
+import { defineToolkit, defineTool } from '../../core/define.js';
+import { inferToolScope } from '../../core/scope.js';
+import { GCONTACTS_ICON } from './icon.js';
+import { googleContactsTools } from './tools/index.js';
+export default defineToolkit({
+    id: 'google-contacts',
+    displayName: 'Google Contacts',
+    shortDescription: 'Create, search, and manage Google Contacts people, groups, and directory profiles.',
+    category: 'CRM',
+    icon: GCONTACTS_ICON,
+    auth: {
+        type: 'oauth2',
+        tokenField: 'googleContactsToken',
+        provider: {
+            slug: 'google-contacts',
+            env: { clientId: 'GOOGLE_CONTACTS_CLIENT_ID', clientSecret: 'GOOGLE_CONTACTS_CLIENT_SECRET' },
+            authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+            tokenUrl: 'https://oauth2.googleapis.com/token',
+            scopes: [
+                'https://www.googleapis.com/auth/contacts',
+                'https://www.googleapis.com/auth/contacts.readonly',
+                'https://www.googleapis.com/auth/contacts.other.readonly',
+                'https://www.googleapis.com/auth/directory.readonly',
+                'https://www.googleapis.com/auth/userinfo.email',
+                'https://www.googleapis.com/auth/userinfo.profile',
+            ],
+            exchangeStyle: 'form',
+            extraAuthParams: { access_type: 'offline', prompt: 'consent' },
+            connectDescription: 'Connect Google Contacts to manage people, groups, and directory profiles.',
+            callbackPath: '/api/auth/google-contacts/callback',
+            stateCookie: 'google_contacts_oauth_state',
+        },
+    },
+    allowedHosts: ['people.googleapis.com'],
+    tools: googleContactsTools.map((entry) => defineTool({
+        name: entry.name,
+        description: entry.description,
+        tool: entry.tool,
+        requiredAuth: entry.requiredAuth,
+        scope: entry.scope ?? inferToolScope(entry.name),
+    })),
+    meta: {
+        since: '0.0.8',
+        homepage: 'https://contacts.google.com',
+        docsUrl: 'https://developers.google.com/people',
+    },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/toolkits/google-contacts/tools/client.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const PEOPLE_API_BASE = "https://people.googleapis.com/v1";
+export declare const googleContactsTokenField: z.ZodString;
+export declare function buildQuery(params: Record<string, string | number | boolean | string[] | undefined>): string;
+export declare function peopleRequest(googleContactsToken: string, path: string, options?: {
+    method?: string;
+    query?: Record<string, string | number | boolean | string[] | undefined>;
+    body?: unknown;
+}): Promise<{
+    ok: false;
+    error: any;
+    data?: undefined;
+} | {
+    ok: true;
+    data: any;
+    error?: undefined;
+}>;
+export declare function normalizeGroupId(id: string): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/toolkits/google-contacts/tools/client.js

@@ -0,0 +1,44 @@
+// @ts-nocheck
+import { z } from 'zod';
+export const PEOPLE_API_BASE = 'https://people.googleapis.com/v1';
+export const googleContactsTokenField = z.string().describe('Google Contacts (People API) OAuth access token (Bearer)');
+export function buildQuery(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                search.append(key, String(v));
+        }
+        else {
+            search.set(key, String(value));
+        }
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : '';
+}
+export async function peopleRequest(googleContactsToken, path, options) {
+    const url = `${PEOPLE_API_BASE}${path}${buildQuery(options?.query ?? {})}`;
+    const response = await fetch(url, {
+        method: options?.method ?? 'GET',
+        headers: {
+            Authorization: `Bearer ${googleContactsToken}`,
+            ...(options?.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+    if (!response.ok) {
+        const details = await response.json().catch(() => ({}));
+        return { ok: false, error: details };
+    }
+    if (response.status === 204) {
+        return { ok: true, data: { success: true } };
+    }
+    const data = await response.json().catch(() => ({}));
+    return { ok: true, data };
+}
+export function normalizeGroupId(id) {
+    return id.startsWith('contactGroups/') ? id : `contactGroups/${id}`;
+}
+//# sourceMappingURL=client.js.map

package/dist/toolkits/google-contacts/tools/contacts.d.ts

@@ -0,0 +1,94 @@
+export declare const createContact: import("ai").Tool<{
+    personFields: string;
+    googleContactsToken: string;
+    sources?: string[] | undefined;
+    person?: Record<string, any> | undefined;
+    names?: Record<string, any>[] | undefined;
+    emailAddresses?: Record<string, any>[] | undefined;
+    phoneNumbers?: Record<string, any>[] | undefined;
+}, any>;
+export declare const batchCreateContacts: import("ai").Tool<{
+    readMask: string;
+    googleContactsToken: string;
+    contacts: Record<string, any>[];
+    sources?: string[] | undefined;
+}, any>;
+export declare const updateContact: import("ai").Tool<{
+    resourceName: string;
+    googleContactsToken: string;
+    person: Record<string, any>;
+    updatePersonFields: string;
+    personFields?: string | undefined;
+    sources?: string[] | undefined;
+}, any>;
+export declare const batchUpdateContacts: import("ai").Tool<{
+    readMask: string;
+    googleContactsToken: string;
+    contacts: Record<string, any>;
+    updateMask: string;
+    sources?: string[] | undefined;
+}, any>;
+export declare const deleteContact: import("ai").Tool<{
+    resourceName: string;
+    googleContactsToken: string;
+}, any>;
+export declare const batchDeleteContacts: import("ai").Tool<{
+    googleContactsToken: string;
+    resourceNames: string[];
+}, {
+    error: string;
+    details: any;
+    success?: undefined;
+    deletedCount?: undefined;
+    message?: undefined;
+} | {
+    success: boolean;
+    deletedCount: number;
+    error?: undefined;
+    details?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    message: string;
+    details?: undefined;
+    success?: undefined;
+    deletedCount?: undefined;
+}>;
+export declare const getPerson: import("ai").Tool<{
+    resourceName: string;
+    personFields: string;
+    googleContactsToken: string;
+    sources?: string[] | undefined;
+    requestMaskIncludeField?: string | undefined;
+}, any>;
+export declare const batchGetPeople: import("ai").Tool<{
+    personFields: string;
+    googleContactsToken: string;
+    resourceNames: string[];
+    sources?: string[] | undefined;
+}, any>;
+export declare const listConnections: import("ai").Tool<{
+    googleContactsToken: string;
+    pageToken?: string | undefined;
+    personFields?: string | undefined;
+    pageSize?: number | undefined;
+    personId?: string | undefined;
+    syncToken?: string | undefined;
+    requestSyncToken?: boolean | undefined;
+    sortOrder?: "LAST_MODIFIED_ASCENDING" | "LAST_MODIFIED_DESCENDING" | "FIRST_NAME_ASCENDING" | "LAST_NAME_ASCENDING" | undefined;
+}, any>;
+export declare const searchContacts: import("ai").Tool<{
+    query: string;
+    googleContactsToken: string;
+    readMask?: string | undefined;
+    sources?: ("CONTACT" | "PROFILE")[] | undefined;
+    pageSize?: number | undefined;
+}, any>;
+export declare const copyOtherContactToMyContacts: import("ai").Tool<{
+    googleContactsToken: string;
+    otherContactsId: string;
+    copyMask: ("names" | "emailAddresses" | "phoneNumbers")[];
+    readMask?: string | undefined;
+    sources?: string[] | undefined;
+}, any>;
+//# sourceMappingURL=contacts.d.ts.map