@slates-integrations/tableau 0.2.0-rc.8

package/src/tools/manage-alerts.ts

@@ -0,0 +1,139 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { tableauServiceError } from '../lib/errors';
+
+export let manageAlerts = SlateTool.create(spec, {
+  name: 'Manage Data-Driven Alerts',
+  key: 'manage_alerts',
+  description: `List, get, delete data-driven alerts, and add or remove users from alert recipient lists. Data-driven alerts trigger when data in a view meets specified conditions.`
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['list', 'get', 'delete', 'addUser', 'removeUser'])
+        .describe('Operation to perform'),
+      alertId: z
+        .string()
+        .optional()
+        .describe('Alert LUID (required for get, delete, addUser, removeUser)'),
+      userId: z.string().optional().describe('User LUID (for addUser, removeUser)'),
+      pageSize: z.number().optional().describe('Page size for list'),
+      pageNumber: z.number().optional().describe('Page number for list')
+    })
+  )
+  .output(
+    z.object({
+      alerts: z
+        .array(
+          z.object({
+            alertId: z.string(),
+            subject: z.string().optional(),
+            creatorId: z.string().optional(),
+            createdAt: z.string().optional(),
+            updatedAt: z.string().optional()
+          })
+        )
+        .optional(),
+      alert: z
+        .object({
+          alertId: z.string(),
+          subject: z.string().optional(),
+          creatorId: z.string().optional(),
+          createdAt: z.string().optional(),
+          updatedAt: z.string().optional(),
+          frequency: z.string().optional(),
+          ownerName: z.string().optional()
+        })
+        .optional(),
+      totalCount: z.number().optional(),
+      deleted: z.boolean().optional(),
+      userAdded: z.boolean().optional(),
+      userRemoved: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let { action } = ctx.input;
+
+    if (action === 'list') {
+      let result = await client.queryAlerts({
+        pageSize: ctx.input.pageSize,
+        pageNumber: ctx.input.pageNumber
+      });
+      let alerts = (result.dataAlerts?.dataAlert || []).map((a: any) => ({
+        alertId: a.id,
+        subject: a.subject,
+        creatorId: a.creator?.id,
+        createdAt: a.createdAt,
+        updatedAt: a.updatedAt
+      }));
+      return {
+        output: { alerts, totalCount: alerts.length },
+        message: `Found **${alerts.length}** data-driven alerts.`
+      };
+    }
+
+    if (action === 'get') {
+      if (!ctx.input.alertId) throw tableauServiceError('alertId is required for get action.');
+
+      let a = await client.getAlert(ctx.input.alertId);
+      return {
+        output: {
+          alert: {
+            alertId: a.id,
+            subject: a.subject,
+            creatorId: a.creator?.id,
+            createdAt: a.createdAt,
+            updatedAt: a.updatedAt,
+            frequency: a.frequency,
+            ownerName: a.owner?.name
+          }
+        },
+        message: `Retrieved alert **${a.subject}**.`
+      };
+    }
+
+    if (action === 'delete') {
+      if (!ctx.input.alertId)
+        throw tableauServiceError('alertId is required for delete action.');
+
+      await client.deleteAlert(ctx.input.alertId);
+      return {
+        output: { deleted: true },
+        message: `Deleted alert \`${ctx.input.alertId}\`.`
+      };
+    }
+
+    if (action === 'addUser') {
+      if (!ctx.input.alertId) {
+        throw tableauServiceError('alertId is required for addUser action.');
+      }
+      if (!ctx.input.userId)
+        throw tableauServiceError('userId is required for addUser action.');
+
+      await client.addUserToAlert(ctx.input.alertId, ctx.input.userId);
+      return {
+        output: { userAdded: true },
+        message: `Added user \`${ctx.input.userId}\` to alert \`${ctx.input.alertId}\`.`
+      };
+    }
+
+    if (action === 'removeUser') {
+      if (!ctx.input.alertId) {
+        throw tableauServiceError('alertId is required for removeUser action.');
+      }
+      if (!ctx.input.userId)
+        throw tableauServiceError('userId is required for removeUser action.');
+
+      await client.removeUserFromAlert(ctx.input.alertId, ctx.input.userId);
+      return {
+        output: { userRemoved: true },
+        message: `Removed user \`${ctx.input.userId}\` from alert \`${ctx.input.alertId}\`.`
+      };
+    }
+
+    throw tableauServiceError(`Unknown action: ${action}`);
+  })
+  .build();

package/src/tools/manage-collections.ts

@@ -0,0 +1,254 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { tableauServiceError } from '../lib/errors';
+
+let collectionSchema = z.object({
+  collectionId: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  ownerName: z.string().optional(),
+  ownerId: z.string().optional(),
+  visibility: z.string().optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+  totalItemCount: z.number().optional(),
+  permissionedItemCount: z.number().optional()
+});
+
+let collectionItemSchema = z.object({
+  contentLuid: z.string().optional(),
+  contentType: z.string().optional(),
+  contentName: z.string().optional(),
+  collectionLuid: z.string().optional(),
+  addedAt: z.string().optional()
+});
+
+let optionalString = (value: unknown) => (typeof value === 'string' ? value : undefined);
+let optionalIdString = (value: unknown) =>
+  typeof value === 'string' ? value : typeof value === 'number' ? String(value) : undefined;
+
+let collectionItems = (result: any) => {
+  if (Array.isArray(result.items)) return result.items;
+  if (Array.isArray(result.collections)) return result.collections;
+  if (Array.isArray(result.collections?.collection)) return result.collections.collection;
+  return [];
+};
+
+let normalizeCollection = (collection: any) => ({
+  collectionId:
+    optionalString(collection.luid) ||
+    optionalString(collection.collectionLuid) ||
+    optionalIdString(collection.id) ||
+    '',
+  name: optionalString(collection.name),
+  description: optionalString(collection.description),
+  ownerName: optionalString(collection.ownerName),
+  ownerId: optionalString(collection.userId) || optionalString(collection.ownerLuid),
+  visibility: optionalString(collection.visibility),
+  createdAt: optionalString(collection.createdTime) || optionalString(collection.createdAt),
+  updatedAt: optionalString(collection.updatedTime) || optionalString(collection.updatedAt),
+  totalItemCount:
+    collection.totalItemCount != null ? Number(collection.totalItemCount) : undefined,
+  permissionedItemCount:
+    collection.permissionedItemCount != null
+      ? Number(collection.permissionedItemCount)
+      : undefined
+});
+
+let normalizeCollectionItem = (item: any) => ({
+  contentLuid: optionalString(item.content?.luid) || optionalString(item.contentLuid),
+  contentType: optionalString(item.content?.contentType) || optionalString(item.contentType),
+  contentName: optionalString(item.content?.name) || optionalString(item.contentName),
+  collectionLuid: optionalString(item.collectionLuid),
+  addedAt: optionalString(item.addedDate) || optionalString(item.addedAt)
+});
+
+export let manageCollections = SlateTool.create(spec, {
+  name: 'Manage Collections',
+  key: 'manage_collections',
+  description: `List, get, create, update, or delete collections, and add, remove, or list collection items. Collections are curated groups of Tableau content.`,
+  tags: { destructive: true }
+})
+  .input(
+    z.object({
+      action: z
+        .enum([
+          'list',
+          'get',
+          'create',
+          'update',
+          'delete',
+          'listItems',
+          'addItems',
+          'removeItems'
+        ])
+        .describe('Operation to perform'),
+      collectionId: z
+        .string()
+        .optional()
+        .describe('Collection LUID (required except for list and create)'),
+      name: z.string().optional().describe('Collection name (required for create)'),
+      description: z.string().optional().describe('Collection description'),
+      ownerId: z
+        .string()
+        .optional()
+        .describe(
+          'Owner user LUID for update actions. Defaults to the authenticated Tableau user.'
+        ),
+      items: z
+        .array(
+          z.object({
+            contentLuid: z.string().describe('LUID of the content item'),
+            contentType: z.string().describe('Tableau content type, such as workbook or view'),
+            contentName: z.string().optional().describe('Display name of the content item')
+          })
+        )
+        .optional()
+        .describe('Items to add or remove from the collection'),
+      pageSize: z.number().int().positive().optional().describe('Page size for list actions'),
+      pageNumber: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page number for list actions'),
+      filter: z.string().optional().describe('Filter expression for list actions'),
+      sort: z.string().optional().describe('Sort expression for list actions')
+    })
+  )
+  .output(
+    z.object({
+      collections: z.array(collectionSchema).optional(),
+      collection: collectionSchema.optional(),
+      items: z.array(collectionItemSchema).optional(),
+      totalCount: z.number().optional(),
+      deleted: z.boolean().optional(),
+      updatedItems: z.any().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let { action } = ctx.input;
+
+    if (action === 'list') {
+      let result = await client.queryCollections({
+        pageSize: ctx.input.pageSize,
+        pageNumber: ctx.input.pageNumber,
+        filter: ctx.input.filter,
+        sort: ctx.input.sort
+      });
+      let collections = collectionItems(result).map(normalizeCollection);
+      let pagination = result.pagination || {};
+      return {
+        output: {
+          collections,
+          totalCount: Number(
+            result.totalCount || pagination.totalAvailable || collections.length
+          )
+        },
+        message: `Found **${collections.length}** collections.`
+      };
+    }
+
+    if (action === 'create') {
+      if (!ctx.input.name) throw tableauServiceError('name is required for create action.');
+
+      let collection = await client.createCollection(ctx.input.name, ctx.input.description);
+      return {
+        output: {
+          collection: normalizeCollection(collection)
+        },
+        message: `Created collection **${collection.name}**.`
+      };
+    }
+
+    if (!ctx.input.collectionId) {
+      throw tableauServiceError(`collectionId is required for ${action} action.`);
+    }
+
+    if (action === 'get') {
+      let collection = await client.getCollection(ctx.input.collectionId);
+      return {
+        output: {
+          collection: normalizeCollection(collection)
+        },
+        message: `Retrieved collection **${collection.name}**.`
+      };
+    }
+
+    if (action === 'update') {
+      if (ctx.input.name === undefined && ctx.input.description === undefined) {
+        throw tableauServiceError('Provide name or description to update a collection.');
+      }
+
+      let collection = await client.updateCollection(ctx.input.collectionId, {
+        name: ctx.input.name,
+        description: ctx.input.description,
+        ownerId: ctx.input.ownerId
+      });
+      return {
+        output: {
+          collection: normalizeCollection(collection)
+        },
+        message: `Updated collection **${collection.name}**.`
+      };
+    }
+
+    if (action === 'delete') {
+      await client.deleteCollection(ctx.input.collectionId);
+      return {
+        output: { deleted: true },
+        message: `Deleted collection \`${ctx.input.collectionId}\`.`
+      };
+    }
+
+    if (action === 'listItems') {
+      let result = await client.listCollectionItems(ctx.input.collectionId, {
+        pageSize: ctx.input.pageSize,
+        pageNumber: ctx.input.pageNumber,
+        filter: ctx.input.filter,
+        sort: ctx.input.sort
+      });
+      let items = (result.items || []).map(normalizeCollectionItem);
+      let pagination = result.pagination || {};
+      return {
+        output: {
+          items,
+          totalCount: Number(result.totalCount || pagination.totalAvailable || items.length)
+        },
+        message: `Found **${items.length}** collection items.`
+      };
+    }
+
+    if (action === 'addItems') {
+      if (!ctx.input.items?.length) {
+        throw tableauServiceError('items is required for addItems action.');
+      }
+
+      let result = await client.addItemsToCollection(ctx.input.collectionId, ctx.input.items);
+      return {
+        output: { updatedItems: result },
+        message: `Added **${ctx.input.items.length}** item(s) to collection \`${ctx.input.collectionId}\`.`
+      };
+    }
+
+    if (action === 'removeItems') {
+      if (!ctx.input.items?.length) {
+        throw tableauServiceError('items is required for removeItems action.');
+      }
+
+      let result = await client.removeItemsFromCollection(
+        ctx.input.collectionId,
+        ctx.input.items
+      );
+      return {
+        output: { updatedItems: result },
+        message: `Removed **${ctx.input.items.length}** item(s) from collection \`${ctx.input.collectionId}\`.`
+      };
+    }
+
+    throw tableauServiceError(`Unknown action: ${action}`);
+  })
+  .build();

package/src/tools/manage-custom-views.ts

@@ -0,0 +1,159 @@
+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 customViewOutputSchema = z.object({
+  customViewId: z.string(),
+  name: z.string().optional(),
+  ownerId: z.string().optional(),
+  ownerName: z.string().optional(),
+  workbookId: z.string().optional(),
+  viewId: z.string().optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional()
+});
+
+let normalizeCustomView = (customView: any) => ({
+  customViewId: customView.id,
+  name: customView.name,
+  ownerId: customView.owner?.id,
+  ownerName: customView.owner?.name,
+  workbookId: customView.workbook?.id,
+  viewId: customView.view?.id,
+  createdAt: customView.createdAt,
+  updatedAt: customView.updatedAt
+});
+
+export let manageCustomViews = SlateTool.create(spec, {
+  name: 'Manage Custom Views',
+  key: 'manage_custom_views',
+  description: `List, get, update, delete, or export Tableau custom views. Custom views are saved user-specific configurations of workbook views.`,
+  tags: { destructive: true }
+})
+  .input(
+    z.object({
+      action: z
+        .enum(['list', 'get', 'update', 'delete', 'export'])
+        .describe('Operation to perform'),
+      customViewId: z
+        .string()
+        .optional()
+        .describe('Custom view LUID (required for get, update, delete, export)'),
+      name: z.string().optional().describe('New custom view name for update'),
+      ownerUserId: z.string().optional().describe('New owner user LUID for update'),
+      exportFormat: z
+        .enum(['csv', 'image', 'pdf'])
+        .optional()
+        .describe('Format to export for the export action'),
+      pageSize: z.number().int().positive().optional().describe('Page size for list'),
+      pageNumber: z.number().int().positive().optional().describe('Page number for list'),
+      maxAgeMinutes: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Minimum cache age before Tableau refreshes exported content'),
+      filters: z
+        .record(z.string(), filterValueSchema)
+        .optional()
+        .describe('View filters keyed by field name; sent as vf_<field>=value')
+    })
+  )
+  .output(
+    z.object({
+      customViews: z.array(customViewOutputSchema).optional(),
+      customView: customViewOutputSchema.optional(),
+      totalCount: z.number().optional(),
+      deleted: z.boolean().optional(),
+      exportFormat: z.enum(['csv', 'image', 'pdf']).optional(),
+      contentType: z.string().optional(),
+      csvData: z.string().optional(),
+      contentBase64: z.string().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let { action } = ctx.input;
+
+    if (action === 'list') {
+      let result = await client.queryCustomViews({
+        pageSize: ctx.input.pageSize,
+        pageNumber: ctx.input.pageNumber
+      });
+      let pagination = result.pagination || {};
+      let customViews = (result.customViews?.customView || []).map(normalizeCustomView);
+      return {
+        output: {
+          customViews,
+          totalCount: Number(pagination.totalAvailable || customViews.length)
+        },
+        message: `Found **${customViews.length}** custom views.`
+      };
+    }
+
+    if (!ctx.input.customViewId) {
+      throw tableauServiceError(`customViewId is required for ${action} action.`);
+    }
+
+    if (action === 'get') {
+      let customView = await client.getCustomView(ctx.input.customViewId);
+      return {
+        output: { customView: normalizeCustomView(customView) },
+        message: `Retrieved custom view **${customView.name}**.`
+      };
+    }
+
+    if (action === 'update') {
+      if (ctx.input.name === undefined && ctx.input.ownerUserId === undefined) {
+        throw tableauServiceError('Provide name or ownerUserId to update a custom view.');
+      }
+
+      let customView = await client.updateCustomView(ctx.input.customViewId, {
+        name: ctx.input.name,
+        ownerUserId: ctx.input.ownerUserId
+      });
+      return {
+        output: { customView: normalizeCustomView(customView) },
+        message: `Updated custom view **${customView.name}**.`
+      };
+    }
+
+    if (action === 'delete') {
+      await client.deleteCustomView(ctx.input.customViewId);
+      return {
+        output: { deleted: true },
+        message: `Deleted custom view \`${ctx.input.customViewId}\`.`
+      };
+    }
+
+    if (action === 'export') {
+      if (!ctx.input.exportFormat) {
+        throw tableauServiceError('exportFormat is required for export action.');
+      }
+
+      let result = await client.exportCustomView(
+        ctx.input.customViewId,
+        ctx.input.exportFormat,
+        {
+          maxAgeMinutes: ctx.input.maxAgeMinutes,
+          filters: ctx.input.filters
+        }
+      );
+      return {
+        output: {
+          exportFormat: ctx.input.exportFormat,
+          contentType: result.contentType,
+          csvData: result.encoding === 'text' ? result.data : undefined,
+          contentBase64: result.encoding === 'base64' ? result.data : undefined
+        },
+        message: `Exported custom view \`${ctx.input.customViewId}\` as ${ctx.input.exportFormat}.`
+      };
+    }
+
+    throw tableauServiceError(`Unknown action: ${action}`);
+  })
+  .build();

package/src/tools/manage-datasource.ts

@@ -0,0 +1,129 @@
+import { SlateTool } from 'slates';
+import { z } from 'zod';
+import { spec } from '../spec';
+import { createClient } from '../lib/helpers';
+import { tableauServiceError } from '../lib/errors';
+
+export let manageDatasource = SlateTool.create(spec, {
+  name: 'Manage Data Source',
+  key: 'manage_datasource',
+  description: `Get details, update, delete, or trigger extract refresh for a data source. Use the **action** field to select the operation.`,
+  tags: { destructive: true }
+})
+  .input(
+    z.object({
+      action: z.enum(['get', 'update', 'delete', 'refresh']).describe('Operation to perform'),
+      datasourceId: z.string().describe('LUID of the data source'),
+      name: z.string().optional().describe('New name (for update)'),
+      description: z.string().optional().describe('New description (for update)'),
+      projectId: z.string().optional().describe('New project LUID (for update)'),
+      ownerUserId: z.string().optional().describe('New owner LUID (for update)'),
+      isCertified: z.boolean().optional().describe('Certification status (for update)'),
+      certificationNote: z.string().optional().describe('Certification note (for update)')
+    })
+  )
+  .output(
+    z.object({
+      datasourceId: z.string().optional(),
+      name: z.string().optional(),
+      description: z.string().optional(),
+      contentUrl: z.string().optional(),
+      type: z.string().optional(),
+      isCertified: z.boolean().optional(),
+      certificationNote: z.string().optional(),
+      projectId: z.string().optional(),
+      projectName: z.string().optional(),
+      ownerId: z.string().optional(),
+      createdAt: z.string().optional(),
+      updatedAt: z.string().optional(),
+      connections: z.array(z.any()).optional(),
+      jobId: z.string().optional(),
+      deleted: z.boolean().optional()
+    })
+  )
+  .handleInvocation(async ctx => {
+    let client = createClient(ctx.config, ctx.auth);
+    let { action, datasourceId } = ctx.input;
+
+    if (action === 'get') {
+      let ds = await client.getDatasource(datasourceId);
+      let conns = await client.getDatasourceConnections(datasourceId);
+
+      return {
+        output: {
+          datasourceId: ds.id,
+          name: ds.name,
+          description: ds.description,
+          contentUrl: ds.contentUrl,
+          type: ds.type,
+          isCertified: ds.isCertified,
+          certificationNote: ds.certificationNote,
+          projectId: ds.project?.id,
+          projectName: ds.project?.name,
+          ownerId: ds.owner?.id,
+          createdAt: ds.createdAt,
+          updatedAt: ds.updatedAt,
+          connections: conns.connections?.connection || []
+        },
+        message: `Retrieved data source **${ds.name}** with ${(conns.connections?.connection || []).length} connections.`
+      };
+    }
+
+    if (action === 'update') {
+      if (
+        ctx.input.name === undefined &&
+        ctx.input.description === undefined &&
+        ctx.input.projectId === undefined &&
+        ctx.input.ownerUserId === undefined &&
+        ctx.input.isCertified === undefined &&
+        ctx.input.certificationNote === undefined
+      ) {
+        throw tableauServiceError('Provide at least one field to update a data source.');
+      }
+
+      let ds = await client.updateDatasource(datasourceId, {
+        name: ctx.input.name,
+        description: ctx.input.description,
+        projectId: ctx.input.projectId,
+        ownerUserId: ctx.input.ownerUserId,
+        isCertified: ctx.input.isCertified,
+        certificationNote: ctx.input.certificationNote
+      });
+
+      return {
+        output: {
+          datasourceId: ds.id,
+          name: ds.name,
+          description: ds.description,
+          contentUrl: ds.contentUrl,
+          type: ds.type,
+          isCertified: ds.isCertified,
+          certificationNote: ds.certificationNote,
+          projectId: ds.project?.id,
+          projectName: ds.project?.name,
+          ownerId: ds.owner?.id,
+          updatedAt: ds.updatedAt
+        },
+        message: `Updated data source **${ds.name}**.`
+      };
+    }
+
+    if (action === 'delete') {
+      await client.deleteDatasource(datasourceId);
+      return {
+        output: { datasourceId, deleted: true },
+        message: `Deleted data source \`${datasourceId}\`.`
+      };
+    }
+
+    if (action === 'refresh') {
+      let job = await client.refreshDatasource(datasourceId);
+      return {
+        output: { datasourceId, jobId: job?.id },
+        message: `Triggered extract refresh for data source \`${datasourceId}\`. Job ID: \`${job?.id}\`.`
+      };
+    }
+
+    throw tableauServiceError(`Unknown action: ${action}`);
+  })
+  .build();