@hasna/connectors 0.0.1

package/connectors/connect-figma/src/api/comments.ts

@@ -0,0 +1,114 @@
+import type { FigmaClient } from './client';
+import type {
+  Comment,
+  CommentsResponse,
+  CommentRequest,
+  ClientMeta,
+} from '../types';
+
+/**
+ * Figma Comments API
+ */
+export class CommentsApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * List comments on a file
+   * @param fileKey - The file key
+   * @param options - Optional parameters
+   */
+  async listComments(
+    fileKey: string,
+    options: {
+      as_md?: boolean;
+    } = {}
+  ): Promise<CommentsResponse> {
+    return this.client.request<CommentsResponse>(`/files/${fileKey}/comments`, {
+      params: options as Record<string, string | number | boolean | undefined>,
+    });
+  }
+
+  /**
+   * Post a comment on a file
+   * @param fileKey - The file key
+   * @param message - The comment message
+   * @param options - Optional parameters
+   */
+  async postComment(
+    fileKey: string,
+    message: string,
+    options: {
+      client_meta?: ClientMeta;
+      comment_id?: string;
+    } = {}
+  ): Promise<Comment> {
+    const body: CommentRequest = {
+      message,
+      ...options,
+    };
+
+    return this.client.request<Comment>(`/files/${fileKey}/comments`, {
+      method: 'POST',
+      body,
+    });
+  }
+
+  /**
+   * Reply to a comment
+   * @param fileKey - The file key
+   * @param commentId - The parent comment ID
+   * @param message - The reply message
+   */
+  async replyToComment(
+    fileKey: string,
+    commentId: string,
+    message: string
+  ): Promise<Comment> {
+    return this.postComment(fileKey, message, { comment_id: commentId });
+  }
+
+  /**
+   * Delete a comment
+   * @param fileKey - The file key
+   * @param commentId - The comment ID
+   */
+  async deleteComment(fileKey: string, commentId: string): Promise<void> {
+    await this.client.request<void>(`/files/${fileKey}/comments/${commentId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /**
+   * Add a reaction to a comment
+   * @param fileKey - The file key
+   * @param commentId - The comment ID
+   * @param emoji - The emoji to react with
+   */
+  async addReaction(
+    fileKey: string,
+    commentId: string,
+    emoji: string
+  ): Promise<void> {
+    await this.client.request<void>(`/files/${fileKey}/comments/${commentId}/reactions`, {
+      method: 'POST',
+      body: { emoji },
+    });
+  }
+
+  /**
+   * Delete a reaction from a comment
+   * @param fileKey - The file key
+   * @param commentId - The comment ID
+   * @param emoji - The emoji to remove
+   */
+  async deleteReaction(
+    fileKey: string,
+    commentId: string,
+    emoji: string
+  ): Promise<void> {
+    await this.client.request<void>(`/files/${fileKey}/comments/${commentId}/reactions`, {
+      method: 'DELETE',
+      params: { emoji },
+    });
+  }
+}

package/connectors/connect-figma/src/api/components.ts

@@ -0,0 +1,82 @@
+import type { FigmaClient } from './client';
+import type {
+  TeamComponentsResponse,
+  TeamComponentSetsResponse,
+  Component,
+  ComponentSet,
+} from '../types';
+
+/**
+ * Figma Components API
+ */
+export class ComponentsApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get team components
+   * @param teamId - The team ID
+   * @param options - Optional parameters
+   */
+  async getTeamComponents(
+    teamId: string,
+    options: {
+      page_size?: number;
+      after?: number;
+      before?: number;
+    } = {}
+  ): Promise<TeamComponentsResponse> {
+    return this.client.request<TeamComponentsResponse>(`/teams/${teamId}/components`, {
+      params: options as Record<string, string | number | boolean | undefined>,
+    });
+  }
+
+  /**
+   * Get team component sets
+   * @param teamId - The team ID
+   * @param options - Optional parameters
+   */
+  async getTeamComponentSets(
+    teamId: string,
+    options: {
+      page_size?: number;
+      after?: number;
+      before?: number;
+    } = {}
+  ): Promise<TeamComponentSetsResponse> {
+    return this.client.request<TeamComponentSetsResponse>(`/teams/${teamId}/component_sets`, {
+      params: options as Record<string, string | number | boolean | undefined>,
+    });
+  }
+
+  /**
+   * Get file components
+   * @param fileKey - The file key
+   */
+  async getFileComponents(fileKey: string): Promise<{ meta: { components: Component[] } }> {
+    return this.client.request<{ meta: { components: Component[] } }>(`/files/${fileKey}/components`);
+  }
+
+  /**
+   * Get file component sets
+   * @param fileKey - The file key
+   */
+  async getFileComponentSets(fileKey: string): Promise<{ meta: { component_sets: ComponentSet[] } }> {
+    return this.client.request<{ meta: { component_sets: ComponentSet[] } }>(`/files/${fileKey}/component_sets`);
+  }
+
+  /**
+   * Get a specific component by key
+   * @param componentKey - The component key
+   */
+  async getComponent(componentKey: string): Promise<{ meta: Component }> {
+    return this.client.request<{ meta: Component }>(`/components/${componentKey}`);
+  }
+
+  /**
+   * Get a specific component set by key
+   * @param componentSetKey - The component set key
+   */
+  async getComponentSet(componentSetKey: string): Promise<{ meta: ComponentSet }> {
+    return this.client.request<{ meta: ComponentSet }>(`/component_sets/${componentSetKey}`);
+  }
+}

package/connectors/connect-figma/src/api/devresources.ts

@@ -0,0 +1,78 @@
+import type { FigmaClient } from './client';
+import type {
+  DevResource,
+  DevResourcesResponse,
+  DevResourceCreateRequest,
+} from '../types';
+
+/**
+ * Figma Dev Resources API
+ */
+export class DevResourcesApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get dev resources for a file
+   * @param fileKey - The file key
+   * @param nodeIds - Optional array of node IDs to filter by
+   */
+  async getDevResources(
+    fileKey: string,
+    nodeIds?: string[]
+  ): Promise<DevResourcesResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {};
+    if (nodeIds && nodeIds.length > 0) {
+      params.node_ids = nodeIds.join(',');
+    }
+
+    return this.client.request<DevResourcesResponse>(`/files/${fileKey}/dev_resources`, {
+      params,
+    });
+  }
+
+  /**
+   * Create dev resources for a file
+   * @param fileKey - The file key
+   * @param devResources - Array of dev resources to create
+   */
+  async createDevResources(
+    fileKey: string,
+    devResources: DevResourceCreateRequest[]
+  ): Promise<DevResourcesResponse> {
+    return this.client.request<DevResourcesResponse>(`/files/${fileKey}/dev_resources`, {
+      method: 'POST',
+      body: { dev_resources: devResources },
+    });
+  }
+
+  /**
+   * Update a dev resource
+   * @param fileKey - The file key
+   * @param devResourceId - The dev resource ID
+   * @param updates - Fields to update
+   */
+  async updateDevResource(
+    fileKey: string,
+    devResourceId: string,
+    updates: {
+      name?: string;
+      url?: string;
+    }
+  ): Promise<DevResource> {
+    return this.client.request<DevResource>(`/files/${fileKey}/dev_resources/${devResourceId}`, {
+      method: 'PUT',
+      body: updates,
+    });
+  }
+
+  /**
+   * Delete a dev resource
+   * @param fileKey - The file key
+   * @param devResourceId - The dev resource ID
+   */
+  async deleteDevResource(fileKey: string, devResourceId: string): Promise<void> {
+    await this.client.request<void>(`/files/${fileKey}/dev_resources/${devResourceId}`, {
+      method: 'DELETE',
+    });
+  }
+}

package/connectors/connect-figma/src/api/files.ts

@@ -0,0 +1,132 @@
+import type { FigmaClient } from './client';
+import type {
+  FileResponse,
+  FileNodesResponse,
+  FileMetaResponse,
+  ImageResponse,
+  ImageFillsResponse,
+  ImageExportOptions,
+  VersionsResponse,
+} from '../types';
+
+/**
+ * Figma Files API
+ */
+export class FilesApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get file information
+   * @param fileKey - The file key (can be extracted from the Figma URL)
+   * @param options - Optional parameters
+   */
+  async getFile(
+    fileKey: string,
+    options: {
+      version?: string;
+      ids?: string[];
+      depth?: number;
+      geometry?: 'paths' | 'bounds';
+      plugin_data?: string;
+      branch_data?: boolean;
+    } = {}
+  ): Promise<FileResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {
+      version: options.version,
+      depth: options.depth,
+      geometry: options.geometry,
+      plugin_data: options.plugin_data,
+      branch_data: options.branch_data,
+    };
+
+    if (options.ids && options.ids.length > 0) {
+      params.ids = options.ids.join(',');
+    }
+
+    return this.client.request<FileResponse>(`/files/${fileKey}`, { params });
+  }
+
+  /**
+   * Get specific nodes from a file
+   * @param fileKey - The file key
+   * @param nodeIds - The IDs of the nodes to retrieve
+   * @param options - Optional parameters
+   */
+  async getFileNodes(
+    fileKey: string,
+    nodeIds: string[],
+    options: {
+      version?: string;
+      depth?: number;
+      geometry?: 'paths' | 'bounds';
+      plugin_data?: string;
+    } = {}
+  ): Promise<FileNodesResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {
+      ids: nodeIds.join(','),
+      version: options.version,
+      depth: options.depth,
+      geometry: options.geometry,
+      plugin_data: options.plugin_data,
+    };
+
+    return this.client.request<FileNodesResponse>(`/files/${fileKey}/nodes`, { params });
+  }
+
+  /**
+   * Export images from a file
+   * @param fileKey - The file key
+   * @param options - Export options
+   */
+  async getImages(
+    fileKey: string,
+    options: ImageExportOptions
+  ): Promise<ImageResponse> {
+    const params: Record<string, string | number | boolean | undefined> = {
+      ids: options.ids.join(','),
+      scale: options.scale,
+      format: options.format,
+      svg_include_id: options.svg_include_id,
+      svg_include_node_id: options.svg_include_node_id,
+      svg_simplify_stroke: options.svg_simplify_stroke,
+      use_absolute_bounds: options.use_absolute_bounds,
+      version: options.version,
+    };
+
+    return this.client.request<ImageResponse>(`/images/${fileKey}`, { params });
+  }
+
+  /**
+   * Get image fills (URLs to images used in image fills)
+   * @param fileKey - The file key
+   */
+  async getImageFills(fileKey: string): Promise<ImageFillsResponse> {
+    return this.client.request<ImageFillsResponse>(`/files/${fileKey}/images`);
+  }
+
+  /**
+   * Get file versions
+   * @param fileKey - The file key
+   * @param options - Optional parameters
+   */
+  async getVersions(
+    fileKey: string,
+    options: {
+      page_size?: number;
+      before?: string;
+      after?: string;
+    } = {}
+  ): Promise<VersionsResponse> {
+    return this.client.request<VersionsResponse>(`/files/${fileKey}/versions`, {
+      params: options as Record<string, string | number | boolean | undefined>,
+    });
+  }
+
+  /**
+   * Get file metadata (lightweight endpoint without document tree)
+   * @param fileKey - The file key
+   */
+  async getFileMeta(fileKey: string): Promise<FileMetaResponse> {
+    return this.client.request<FileMetaResponse>(`/files/${fileKey}/meta`);
+  }
+}

package/connectors/connect-figma/src/api/index.ts

@@ -0,0 +1,86 @@
+import type { FigmaConfig } from '../types';
+import { FigmaClient } from './client';
+import { FilesApi } from './files';
+import { CommentsApi } from './comments';
+import { TeamsApi } from './teams';
+import { ProjectsApi } from './projects';
+import { ComponentsApi } from './components';
+import { StylesApi } from './styles';
+import { WebhooksApi } from './webhooks';
+import { UsersApi } from './users';
+import { VariablesApi } from './variables';
+import { DevResourcesApi } from './devresources';
+
+/**
+ * Main Figma Connector class
+ * Provides access to all Figma API endpoints
+ */
+export class Figma {
+  private readonly client: FigmaClient;
+
+  // Service APIs
+  public readonly files: FilesApi;
+  public readonly comments: CommentsApi;
+  public readonly teams: TeamsApi;
+  public readonly projects: ProjectsApi;
+  public readonly components: ComponentsApi;
+  public readonly styles: StylesApi;
+  public readonly webhooks: WebhooksApi;
+  public readonly users: UsersApi;
+  public readonly variables: VariablesApi;
+  public readonly devResources: DevResourcesApi;
+
+  constructor(config: FigmaConfig) {
+    this.client = new FigmaClient(config);
+    this.files = new FilesApi(this.client);
+    this.comments = new CommentsApi(this.client);
+    this.teams = new TeamsApi(this.client);
+    this.projects = new ProjectsApi(this.client);
+    this.components = new ComponentsApi(this.client);
+    this.styles = new StylesApi(this.client);
+    this.webhooks = new WebhooksApi(this.client);
+    this.users = new UsersApi(this.client);
+    this.variables = new VariablesApi(this.client);
+    this.devResources = new DevResourcesApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for FIGMA_ACCESS_TOKEN or FIGMA_TOKEN
+   */
+  static fromEnv(): Figma {
+    const accessToken = process.env.FIGMA_ACCESS_TOKEN || process.env.FIGMA_TOKEN;
+
+    if (!accessToken) {
+      throw new Error('FIGMA_ACCESS_TOKEN or FIGMA_TOKEN environment variable is required');
+    }
+
+    return new Figma({ accessToken });
+  }
+
+  /**
+   * Get a preview of the access token (for debugging)
+   */
+  getAccessTokenPreview(): string {
+    return this.client.getAccessTokenPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): FigmaClient {
+    return this.client;
+  }
+}
+
+export { FigmaClient } from './client';
+export { FilesApi } from './files';
+export { CommentsApi } from './comments';
+export { TeamsApi } from './teams';
+export { ProjectsApi } from './projects';
+export { ComponentsApi } from './components';
+export { StylesApi } from './styles';
+export { WebhooksApi } from './webhooks';
+export { UsersApi } from './users';
+export { VariablesApi } from './variables';
+export { DevResourcesApi } from './devresources';

package/connectors/connect-figma/src/api/projects.ts

@@ -0,0 +1,36 @@
+import type { FigmaClient } from './client';
+import type {
+  TeamProjectsResponse,
+  ProjectFilesResponse,
+} from '../types';
+
+/**
+ * Figma Projects API
+ */
+export class ProjectsApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get team projects
+   * @param teamId - The team ID
+   */
+  async getTeamProjects(teamId: string): Promise<TeamProjectsResponse> {
+    return this.client.request<TeamProjectsResponse>(`/teams/${teamId}/projects`);
+  }
+
+  /**
+   * Get files in a project
+   * @param projectId - The project ID
+   * @param options - Optional parameters
+   */
+  async getProjectFiles(
+    projectId: string,
+    options: {
+      branch_data?: boolean;
+    } = {}
+  ): Promise<ProjectFilesResponse> {
+    return this.client.request<ProjectFilesResponse>(`/projects/${projectId}/files`, {
+      params: options as Record<string, string | number | boolean | undefined>,
+    });
+  }
+}

package/connectors/connect-figma/src/api/styles.ts

@@ -0,0 +1,46 @@
+import type { FigmaClient } from './client';
+import type {
+  TeamStylesResponse,
+  Style,
+} from '../types';
+
+/**
+ * Figma Styles API
+ */
+export class StylesApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get team styles
+   * @param teamId - The team ID
+   * @param options - Optional parameters
+   */
+  async getTeamStyles(
+    teamId: string,
+    options: {
+      page_size?: number;
+      after?: number;
+      before?: number;
+    } = {}
+  ): Promise<TeamStylesResponse> {
+    return this.client.request<TeamStylesResponse>(`/teams/${teamId}/styles`, {
+      params: options as Record<string, string | number | boolean | undefined>,
+    });
+  }
+
+  /**
+   * Get file styles
+   * @param fileKey - The file key
+   */
+  async getFileStyles(fileKey: string): Promise<{ meta: { styles: Style[] } }> {
+    return this.client.request<{ meta: { styles: Style[] } }>(`/files/${fileKey}/styles`);
+  }
+
+  /**
+   * Get a specific style by key
+   * @param styleKey - The style key
+   */
+  async getStyle(styleKey: string): Promise<{ meta: Style }> {
+    return this.client.request<{ meta: Style }>(`/styles/${styleKey}`);
+  }
+}

package/connectors/connect-figma/src/api/teams.ts

@@ -0,0 +1,17 @@
+import type { FigmaClient } from './client';
+import type { TeamProjectsResponse } from '../types';
+
+/**
+ * Figma Teams API
+ */
+export class TeamsApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get team projects
+   * @param teamId - The team ID
+   */
+  async getProjects(teamId: string): Promise<TeamProjectsResponse> {
+    return this.client.request<TeamProjectsResponse>(`/teams/${teamId}/projects`);
+  }
+}

package/connectors/connect-figma/src/api/users.ts

@@ -0,0 +1,16 @@
+import type { FigmaClient } from './client';
+import type { User } from '../types';
+
+/**
+ * Figma Users API
+ */
+export class UsersApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get the current user
+   */
+  async getMe(): Promise<User> {
+    return this.client.request<User>('/me');
+  }
+}

package/connectors/connect-figma/src/api/variables.ts

@@ -0,0 +1,73 @@
+import type { FigmaClient } from './client';
+import type {
+  LocalVariablesResponse,
+  PublishedVariablesResponse,
+} from '../types';
+
+/**
+ * Figma Variables API
+ */
+export class VariablesApi {
+  constructor(private readonly client: FigmaClient) {}
+
+  /**
+   * Get local variables in a file
+   * @param fileKey - The file key
+   */
+  async getLocalVariables(fileKey: string): Promise<LocalVariablesResponse> {
+    return this.client.request<LocalVariablesResponse>(`/files/${fileKey}/variables/local`);
+  }
+
+  /**
+   * Get published variables in a file
+   * @param fileKey - The file key
+   */
+  async getPublishedVariables(fileKey: string): Promise<PublishedVariablesResponse> {
+    return this.client.request<PublishedVariablesResponse>(`/files/${fileKey}/variables/published`);
+  }
+
+  /**
+   * Create/update/delete variables in a file
+   * This endpoint supports bulk operations on variables and variable collections
+   * @param fileKey - The file key
+   * @param operations - The operations to perform
+   */
+  async postVariables(
+    fileKey: string,
+    operations: {
+      variableCollections?: Array<{
+        action: 'CREATE' | 'UPDATE' | 'DELETE';
+        id?: string;
+        name?: string;
+        initialModeId?: string;
+      }>;
+      variableModes?: Array<{
+        action: 'CREATE' | 'UPDATE' | 'DELETE';
+        id?: string;
+        variableCollectionId?: string;
+        name?: string;
+      }>;
+      variables?: Array<{
+        action: 'CREATE' | 'UPDATE' | 'DELETE';
+        id?: string;
+        name?: string;
+        variableCollectionId?: string;
+        resolvedType?: 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+        description?: string;
+        hiddenFromPublishing?: boolean;
+        scopes?: string[];
+        codeSyntax?: Record<string, string>;
+      }>;
+      variableModeValues?: Array<{
+        variableId: string;
+        modeId: string;
+        value: unknown;
+      }>;
+    }
+  ): Promise<LocalVariablesResponse> {
+    return this.client.request<LocalVariablesResponse>(`/files/${fileKey}/variables`, {
+      method: 'POST',
+      body: operations,
+    });
+  }
+}