@slates-integrations/tableau 0.2.0-rc.8

package/src/lib/errors.ts

@@ -0,0 +1,94 @@
+import { ServiceError, badRequestError } from '@lowerdeck/error';
+
+type ErrorResponse = {
+  status?: number;
+  statusText?: string;
+  data?: unknown;
+};
+
+let isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+let pushString = (messages: string[], value: unknown) => {
+  if (typeof value === 'string' && value.trim()) {
+    let trimmed = value.trim();
+    if (!messages.includes(trimmed)) messages.push(trimmed);
+  }
+};
+
+let collectTableauMessages = (value: unknown, messages: string[]) => {
+  if (!isRecord(value)) return;
+
+  pushString(messages, value.summary);
+  pushString(messages, value.detail);
+  pushString(messages, value.message);
+  pushString(messages, value.errorMessage);
+  pushString(messages, value.title);
+
+  if (typeof value.code === 'string' && value.code.trim()) {
+    pushString(messages, `code ${value.code}`);
+  }
+
+  let nestedError = value.error;
+  if (isRecord(nestedError)) collectTableauMessages(nestedError, messages);
+
+  let errors = value.errors;
+  if (Array.isArray(errors)) {
+    for (let item of errors) collectTableauMessages(item, messages);
+  }
+};
+
+let extractTableauMessage = (error: unknown) => {
+  let response = isRecord(error) ? (error.response as ErrorResponse | undefined) : undefined;
+  let errorData = isRecord(error)
+    ? (error.data as Record<string, unknown> | undefined)
+    : undefined;
+  let baggage = isRecord(errorData?.baggage)
+    ? (errorData.baggage as Record<string, unknown>)
+    : undefined;
+  let data = response?.data ?? baggage?.response;
+  let messages: string[] = [];
+
+  if (isRecord(data)) {
+    collectTableauMessages(data, messages);
+  } else if (typeof data === 'string') {
+    pushString(messages, data.slice(0, 500));
+  }
+
+  if (messages.length > 0) {
+    return messages.join(' - ');
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return 'Unknown error';
+};
+
+export let tableauServiceError = (message: string) =>
+  new ServiceError(badRequestError({ message }));
+
+export let tableauApiError = (error: unknown, operation = 'request') => {
+  if (error instanceof ServiceError) return error;
+
+  let response = isRecord(error) ? (error.response as ErrorResponse | undefined) : undefined;
+  let status = response?.status;
+  let statusLabel =
+    status !== undefined
+      ? `HTTP ${status}${response?.statusText ? ` ${response.statusText}` : ''}: `
+      : '';
+
+  let serviceError = tableauServiceError(
+    `Tableau API ${operation} failed: ${statusLabel}${extractTableauMessage(error)}`
+  );
+
+  serviceError.data.reason = 'tableau_api_error';
+  serviceError.data.upstreamStatus = status;
+
+  if (error instanceof Error) {
+    serviceError.setParent(error);
+  }
+
+  return serviceError;
+};

package/src/lib/helpers.ts

@@ -0,0 +1,15 @@
+import { TableauClient } from './client';
+
+export let createClient = (
+  config: { serverUrl: string; apiVersion: string; siteContentUrl: string },
+  auth: { token: string; siteId: string; userId?: string; expiresAt?: string }
+) => {
+  return new TableauClient({
+    serverUrl: config.serverUrl,
+    apiVersion: config.apiVersion,
+    siteId: auth.siteId,
+    token: auth.token,
+    userId: auth.userId,
+    expiresAt: auth.expiresAt
+  });
+};

package/src/lib/normalizers.ts

@@ -0,0 +1,9 @@
+export let normalizeBoolean = (value: unknown) => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    let normalized = value.toLowerCase();
+    if (normalized === 'true') return true;
+    if (normalized === 'false') return false;
+  }
+  return undefined;
+};

package/src/spec.ts

@@ -0,0 +1,12 @@
+import { SlateSpecification } from 'slates';
+import { auth } from './auth';
+import { config } from './config';
+
+export let spec = SlateSpecification.create({
+  key: 'tableau',
+  name: 'Tableau',
+  description: undefined,
+  metadata: {},
+  config,
+  auth
+});

package/src/tools/export-view.ts

@@ -0,0 +1,112 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { tableauServiceError } from '../lib/errors';
+
+let filterValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+let pdfPageTypeSchema = z.enum([
+  'A3',
+  'A4',
+  'A5',
+  'B5',
+  'Executive',
+  'Folio',
+  'Ledger',
+  'Legal',
+  'Letter',
+  'Note',
+  'Quarto',
+  'Tabloid'
+]);
+
+export let exportView = SlateTool.create(spec, {
+  name: 'Export View',
+  key: 'export_view',
+  description: `Export a Tableau view as CSV data, a PNG image, or a PDF file. Supports Tableau view filter query parameters and cache max-age controls.`,
+  tags: { readOnly: true }
+})
+  .input(
+    z.object({
+      viewId: z.string().describe('LUID of the view to export'),
+      format: z.enum(['csv', 'image', 'pdf']).describe('Export format to retrieve'),
+      maxAgeMinutes: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Minimum cache age before Tableau refreshes the exported view'),
+      filters: z
+        .record(z.string(), filterValueSchema)
+        .optional()
+        .describe('View filters keyed by field name; sent as vf_<field>=value'),
+      imageResolution: z
+        .enum(['high'])
+        .optional()
+        .describe('Set to "high" for maximum PNG pixel density'),
+      vizHeight: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Rendered PDF height in pixels'),
+      vizWidth: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Rendered PDF width in pixels'),
+      pdfPageType: pdfPageTypeSchema.optional().describe('PDF page size'),
+      pdfOrientation: z.enum(['Portrait', 'Landscape']).optional().describe('PDF orientation')
+    })
+  )
+  .output(
+    z.object({
+      viewId: z.string(),
+      format: z.enum(['csv', 'image', 'pdf']),
+      contentType: z.string(),
+      csvData: z.string().optional(),
+      contentBase64: z.string().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    if (ctx.input.format !== 'image' && ctx.input.imageResolution !== undefined) {
+      throw tableauServiceError('imageResolution is only valid when format is "image".');
+    }
+    if (ctx.input.format !== 'pdf') {
+      if (
+        ctx.input.vizHeight !== undefined ||
+        ctx.input.vizWidth !== undefined ||
+        ctx.input.pdfPageType !== undefined ||
+        ctx.input.pdfOrientation !== undefined
+      ) {
+        throw tableauServiceError(
+          'vizHeight, vizWidth, pdfPageType, and pdfOrientation are only valid when format is "pdf".'
+        );
+      }
+    }
+
+    let client = createClient(ctx.config, ctx.auth);
+    let result = await client.exportView(ctx.input.viewId, ctx.input.format, {
+      maxAgeMinutes: ctx.input.maxAgeMinutes,
+      filters: ctx.input.filters,
+      imageResolution: ctx.input.imageResolution,
+      vizHeight: ctx.input.vizHeight,
+      vizWidth: ctx.input.vizWidth,
+      pdfPageType: ctx.input.pdfPageType,
+      pdfOrientation: ctx.input.pdfOrientation
+    });
+
+    return {
+      output: {
+        viewId: ctx.input.viewId,
+        format: ctx.input.format,
+        contentType: result.contentType,
+        csvData: result.encoding === 'text' ? result.data : undefined,
+        contentBase64: result.encoding === 'base64' ? result.data : undefined
+      },
+      message: `Exported Tableau view \`${ctx.input.viewId}\` as ${ctx.input.format}.`
+    };
+  })
+  .build();

package/src/tools/get-site-info.ts

@@ -0,0 +1,47 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+
+export let getSiteInfo = SlateTool.create(spec, {
+  name: 'Get Site Info',
+  key: 'get_site_info',
+  description: `Retrieve information about the current Tableau site, including name, URL, storage usage, and configuration settings.`,
+  tags: { readOnly: true }
+})
+  .input(z.object({}))
+  .output(
+    z.object({
+      siteId: z.string(),
+      name: z.string().optional(),
+      contentUrl: z.string().optional(),
+      adminMode: z.string().optional(),
+      state: z.string().optional(),
+      storageQuota: z.number().optional(),
+      numCreators: z.number().optional(),
+      numExplorers: z.number().optional(),
+      numViewers: z.number().optional(),
+      revisionHistoryEnabled: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let site = await client.getSiteInfo();
+
+    return {
+      output: {
+        siteId: site.id,
+        name: site.name,
+        contentUrl: site.contentUrl,
+        adminMode: site.adminMode,
+        state: site.state,
+        storageQuota: site.storageQuota != null ? Number(site.storageQuota) : undefined,
+        numCreators: site.numCreators != null ? Number(site.numCreators) : undefined,
+        numExplorers: site.numExplorers != null ? Number(site.numExplorers) : undefined,
+        numViewers: site.numViewers != null ? Number(site.numViewers) : undefined,
+        revisionHistoryEnabled: site.revisionHistoryEnabled
+      },
+      message: `Site **${site.name}** (state: ${site.state || 'active'}).`
+    };
+  })
+  .build();

package/src/tools/get-view-data.ts

@@ -0,0 +1,31 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+
+export let getViewData = SlateTool.create(spec, {
+  name: 'Get View Data',
+  key: 'get_view_data',
+  description: `Export the underlying data from a Tableau view as CSV. Useful for retrieving the tabular data behind a dashboard visualization.`,
+  tags: { readOnly: true }
+})
+  .input(
+    z.object({
+      viewId: z.string().describe('LUID of the view to export data from')
+    })
+  )
+  .output(
+    z.object({
+      csvData: z.string().describe('CSV content of the view data')
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let csvData = await client.getViewData(ctx.input.viewId);
+
+    return {
+      output: { csvData },
+      message: `Exported CSV data from view \`${ctx.input.viewId}\`.`
+    };
+  })
+  .build();

package/src/tools/index.ts

@@ -0,0 +1,18 @@
+export * from './list-workbooks';
+export * from './manage-workbook';
+export * from './list-datasources';
+export * from './manage-datasource';
+export * from './list-views';
+export * from './get-view-data';
+export * from './export-view';
+export * from './manage-custom-views';
+export * from './manage-users';
+export * from './manage-groups';
+export * from './manage-projects';
+export * from './manage-permissions';
+export * from './manage-jobs';
+export * from './manage-favorites';
+export * from './manage-flows';
+export * from './manage-collections';
+export * from './manage-alerts';
+export * from './get-site-info';

package/src/tools/list-datasources.ts

@@ -0,0 +1,78 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+
+export let listDatasources = SlateTool.create(spec, {
+  name: 'List Data Sources',
+  key: 'list_datasources',
+  description: `List and search data sources on the Tableau site. Supports pagination, filtering, and sorting.`,
+  tags: { readOnly: true }
+})
+  .input(
+    z.object({
+      pageSize: z.number().optional().describe('Number of items per page'),
+      pageNumber: z.number().optional().describe('Page number (1-based)'),
+      filter: z.string().optional().describe('Filter expression (e.g., "name:eq:Sales Data")'),
+      sort: z.string().optional().describe('Sort expression (e.g., "name:asc")')
+    })
+  )
+  .output(
+    z.object({
+      datasources: z.array(
+        z.object({
+          datasourceId: z.string(),
+          name: z.string(),
+          description: z.string().optional(),
+          contentUrl: z.string().optional(),
+          type: z.string().optional(),
+          isCertified: z.boolean().optional(),
+          certificationNote: z.string().optional(),
+          createdAt: z.string().optional(),
+          updatedAt: z.string().optional(),
+          projectId: z.string().optional(),
+          projectName: z.string().optional(),
+          ownerId: z.string().optional()
+        })
+      ),
+      totalCount: z.number(),
+      pageNumber: z.number(),
+      pageSize: z.number()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let result = await client.queryDatasources({
+      pageSize: ctx.input.pageSize,
+      pageNumber: ctx.input.pageNumber,
+      filter: ctx.input.filter,
+      sort: ctx.input.sort
+    });
+
+    let pagination = result.pagination || {};
+    let datasources = (result.datasources?.datasource || []).map((d: any) => ({
+      datasourceId: d.id,
+      name: d.name,
+      description: d.description,
+      contentUrl: d.contentUrl,
+      type: d.type,
+      isCertified: d.isCertified,
+      certificationNote: d.certificationNote,
+      createdAt: d.createdAt,
+      updatedAt: d.updatedAt,
+      projectId: d.project?.id,
+      projectName: d.project?.name,
+      ownerId: d.owner?.id
+    }));
+
+    return {
+      output: {
+        datasources,
+        totalCount: Number(pagination.totalAvailable || 0),
+        pageNumber: Number(pagination.pageNumber || 1),
+        pageSize: Number(pagination.pageSize || datasources.length)
+      },
+      message: `Found **${datasources.length}** data sources (${pagination.totalAvailable || 0} total).`
+    };
+  })
+  .build();

package/src/tools/list-views.ts

@@ -0,0 +1,70 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+
+export let listViews = SlateTool.create(spec, {
+  name: 'List Views',
+  key: 'list_views',
+  description: `List and search views across the Tableau site. Supports pagination, filtering, and sorting.`,
+  tags: { readOnly: true }
+})
+  .input(
+    z.object({
+      pageSize: z.number().optional().describe('Number of items per page'),
+      pageNumber: z.number().optional().describe('Page number (1-based)'),
+      filter: z.string().optional().describe('Filter expression (e.g., "name:eq:Revenue")'),
+      sort: z.string().optional().describe('Sort expression (e.g., "name:asc")')
+    })
+  )
+  .output(
+    z.object({
+      views: z.array(
+        z.object({
+          viewId: z.string(),
+          name: z.string(),
+          contentUrl: z.string().optional(),
+          createdAt: z.string().optional(),
+          updatedAt: z.string().optional(),
+          viewUrlName: z.string().optional(),
+          workbookId: z.string().optional(),
+          ownerId: z.string().optional()
+        })
+      ),
+      totalCount: z.number(),
+      pageNumber: z.number(),
+      pageSize: z.number()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let result = await client.queryViews({
+      pageSize: ctx.input.pageSize,
+      pageNumber: ctx.input.pageNumber,
+      filter: ctx.input.filter,
+      sort: ctx.input.sort
+    });
+
+    let pagination = result.pagination || {};
+    let views = (result.views?.view || []).map((v: any) => ({
+      viewId: v.id,
+      name: v.name,
+      contentUrl: v.contentUrl,
+      createdAt: v.createdAt,
+      updatedAt: v.updatedAt,
+      viewUrlName: v.viewUrlName,
+      workbookId: v.workbook?.id,
+      ownerId: v.owner?.id
+    }));
+
+    return {
+      output: {
+        views,
+        totalCount: Number(pagination.totalAvailable || 0),
+        pageNumber: Number(pagination.pageNumber || 1),
+        pageSize: Number(pagination.pageSize || views.length)
+      },
+      message: `Found **${views.length}** views (${pagination.totalAvailable || 0} total).`
+    };
+  })
+  .build();

package/src/tools/list-workbooks.ts

@@ -0,0 +1,88 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { normalizeBoolean } from '../lib/normalizers';
+
+export let listWorkbooks = SlateTool.create(spec, {
+  name: 'List Workbooks',
+  key: 'list_workbooks',
+  description: `List and search workbooks on the Tableau site. Supports pagination, filtering, and sorting to find specific workbooks.`,
+  tags: { readOnly: true }
+})
+  .input(
+    z.object({
+      pageSize: z
+        .number()
+        .optional()
+        .describe('Number of items per page (default 100, max 1000)'),
+      pageNumber: z.number().optional().describe('Page number to retrieve (1-based)'),
+      filter: z
+        .string()
+        .optional()
+        .describe('Filter expression (e.g., "name:eq:Sales Dashboard")'),
+      sort: z
+        .string()
+        .optional()
+        .describe('Sort expression (e.g., "name:asc" or "updatedAt:desc")')
+    })
+  )
+  .output(
+    z.object({
+      workbooks: z.array(
+        z.object({
+          workbookId: z.string(),
+          name: z.string(),
+          description: z.string().optional(),
+          contentUrl: z.string().optional(),
+          webpageUrl: z.string().optional(),
+          showTabs: z.boolean().optional(),
+          size: z.number().optional(),
+          createdAt: z.string().optional(),
+          updatedAt: z.string().optional(),
+          projectId: z.string().optional(),
+          projectName: z.string().optional(),
+          ownerId: z.string().optional()
+        })
+      ),
+      totalCount: z.number(),
+      pageNumber: z.number(),
+      pageSize: z.number()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let result = await client.queryWorkbooks({
+      pageSize: ctx.input.pageSize,
+      pageNumber: ctx.input.pageNumber,
+      filter: ctx.input.filter,
+      sort: ctx.input.sort
+    });
+
+    let pagination = result.pagination || {};
+    let workbooks = (result.workbooks?.workbook || []).map((w: any) => ({
+      workbookId: w.id,
+      name: w.name,
+      description: w.description,
+      contentUrl: w.contentUrl,
+      webpageUrl: w.webpageUrl,
+      showTabs: normalizeBoolean(w.showTabs),
+      size: w.size ? Number(w.size) : undefined,
+      createdAt: w.createdAt,
+      updatedAt: w.updatedAt,
+      projectId: w.project?.id,
+      projectName: w.project?.name,
+      ownerId: w.owner?.id
+    }));
+
+    return {
+      output: {
+        workbooks,
+        totalCount: Number(pagination.totalAvailable || 0),
+        pageNumber: Number(pagination.pageNumber || 1),
+        pageSize: Number(pagination.pageSize || workbooks.length)
+      },
+      message: `Found **${workbooks.length}** workbooks (${pagination.totalAvailable || 0} total).`
+    };
+  })
+  .build();