@keragon/connector-cli 0.0.1

package/assets/index.ts

@@ -0,0 +1,3 @@
+import path from "path";
+
+export const assets = () => path.join(__dirname, 'assets');

package/assets/templates/add/action/src/components/<%= componentName %>/<%= componentName %>.definition.json.ejs

@@ -0,0 +1,113 @@
+<%
+  function formatComponentTitle(str) {
+    const spaced = str?.replace(/([A-Z])/g, ' $1')?.toLowerCase();
+    return spaced?.charAt(0).toUpperCase() + spaced?.slice(1);
+  }
+
+  const obj = {
+    id: componentId,
+    title: formatComponentTitle(componentName),
+    description: desc,
+    type: "action",
+    sdkVersion: "0.0.1"
+  };
+
+  if (typeof alert !== 'undefined') {
+    obj.alerts = [{
+      type: "info",
+      content: `More info in [article](https://go.keragon.com/${componentName})`
+    }];
+  }
+
+  if (typeof http !== 'undefined') {
+    obj.request = {
+      config: {
+        method: "get",
+        url: "/"
+      },
+    };
+  }
+
+  if (typeof pagination !== 'undefined') {
+    obj.pagination = {
+      strategy: pagination,
+      maxItems: "${ .inputs.maxItems // 250 }"
+    };
+
+    if (pagination === 'offset') {
+      Object.assign(obj.pagination, {
+        pageSize: 100,
+        setPageSize: "${ .request.params.limit = .pagination.pageSize }",
+        setPageToken: "${ .request.params.offset = .pagination.nextPageToken }"
+      });
+    } else if (pagination === 'page') {
+      Object.assign(obj.pagination, {
+        pageSize: 100,
+        setPageSize: "${ .request.params.per_page = .pagination.pageSize }",
+        setPageToken: "${ .request.params.page = .pagination.nextPageToken + 1 }"
+      });
+    } else if (pagination === 'cursor') {
+      Object.assign(obj.pagination, {
+        setPageToken: "${ .request.url = .pagination.nextPageToken }",
+        getNextPageToken: "${ .response.data.next }"
+      });
+    }
+  }
+
+  if (typeof errorHandler !== 'undefined') {
+    obj.response = {
+      errorHandlers: [{
+        condition: "${ .response.status != 200 }",
+        action: "throwError",
+        message: "${ .response.data | tostring }"
+      }]
+    };
+  }
+
+  if (typeof inputs !== 'undefined') {
+    obj.inputs = {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      additionalProperties: false,
+      required: ["id"],
+      properties: {
+        id: {
+          type: "string",
+          title: "ID",
+          dynamicEnum: {
+            componentId: `${connectorId}.get`,
+            processInputs: "${ }",
+            processOutputs: "${ [.[] | {label: .name, value: .id}] }"
+          }
+        }
+      }
+    };
+
+    if (typeof pagination !== 'undefined') {
+      obj.inputs.properties.maxItems = {
+        type: "number",
+        title: "Max items",
+        default: 250
+      };
+    }
+  }
+
+  if (typeof outputs !== 'undefined') {
+    obj.outputs = {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      type: "array",
+      title: "Items",
+      properties: {
+        id: {
+          type: "string",
+          title: "ID"
+        },
+        name: {
+          type: "string",
+          title: "Name"
+        }
+      }
+    };
+  }
+%>
+<%- JSON.stringify(obj, null, 2) %>

package/assets/templates/add/action/src/components/<%= componentName %>/index.ts.ejs

@@ -0,0 +1,5 @@
+import definition from './<%= componentName %>.definition.json';
+
+export default {
+  definition,
+};

package/assets/templates/add/implementation/connector/__tests__/<%= name %>.test.ts.ejs

@@ -0,0 +1,28 @@
+import { 
+  Credentials
+} from '@keragon/connector-sdk';
+import app from '../src';
+const { definition, ctor: <%= firstLetterUpperCase(name) %> } = app;
+
+const setupTest = ({
+  credentials = {
+    authScheme: {
+      id: 'com.keragon.<%= name %>.environments.prod.authSchemes.custom',
+    },
+  }
+}: {
+  credentials?: Credentials
+}) => {
+  const <%= name %> = new <%= firstLetterUpperCase(name) %>({
+    definition, credentials,
+  });
+  return { <%= name %>, credentials }
+};
+
+describe('Connector: <%= firstLetterUpperCase(name) %> should', () => {
+  it('construct connector', async () => {
+    const { <%= name %> } = setupTest({});
+
+    expect(<%= name %>).toBeDefined();
+  });
+});

package/assets/templates/add/implementation/connector/src/<%= name %>.ts.ejs

@@ -0,0 +1,16 @@
+import {
+  ConfigureCredentialsArgs, 
+  <%= isHttp ? 'HttpApp' : 'App' %>,
+} from '@keragon/connector-sdk';
+
+export default class <%= firstLetterUpperCase(name) %> extends <%= isHttp ? 'HttpApp' : 'App' %> {
+  // TODO: default implementation
+  override async configureCredentials(args: ConfigureCredentialsArgs) {
+    const configuredCredentials = await super.configureCredentials(args);
+    const { authScheme } = configuredCredentials;
+    return {
+      ...configuredCredentials,
+      authScheme,
+    };
+  }
+}

package/assets/templates/add/pollingtrigger/__tests__/<%= componentName %>.test.ts.ejs

@@ -0,0 +1,73 @@
+import { CloudEventData } from '@keragon/types';
+import { CloudEvent } from 'cloudevents';
+import app from '../src';
+const { definition, ctor: <%= firstLetterUpperCase(connectorId) %> } = app;
+
+const mockAxiosGet = jest.fn();
+const mockAxiosPost = jest.fn();
+const mockAxiosPut = jest.fn();
+const mockAxiosDelete = jest.fn();
+const mockIsAxiosError = jest.fn();
+jest.mock('axios', () => ({
+  create: jest.fn((defaults) => ({
+    get: mockAxiosGet,
+    post: mockAxiosPost,
+    put: mockAxiosPut,
+    delete: mockAxiosDelete,
+    defaults,
+  })),
+  isAxiosError: jest.fn().mockImplementation(() => (mockIsAxiosError())),
+}));
+
+//Mock Date.now
+const now = 1738876122999;
+jest.useFakeTimers({ now });
+
+const setUpTest = ({
+  store,
+}: {
+  store?: Record<string, unknown>;
+}) => {
+  const <%= connectorId %>: InstanceType<typeof <%= firstLetterUpperCase(connectorId) %>> = new <%= firstLetterUpperCase(connectorId) %>({
+    definition,
+    credentials: {
+      key: 'mockKey',
+      authScheme: {
+        // TODO authScheme
+        id: 'com.keragon.<%= connectorId %>.environments.prod.authSchemes.apiKey',
+      },
+    }
+  });
+
+  const trigger = <%= connectorId %>.constructComponent({ componentId: 'com.keragon.<%= connectorId %>.<%= componentId %>', store });
+  return { <%= connectorId %>, trigger, webhookUrl: 'https://test.com/v1/' };
+};
+
+describe('Component: Trigger com.keragon.<%= connectorId %>.<%= componentId %> should', () => {
+
+  it('.generateSampleEvents returns sample', async () => {
+    // Arrange
+    const { trigger } = setupTest();
+    const mockGetDynamicValue = jest.fn();
+    mockGetDynamicValue
+      .mockResolvedValue([
+      // TODO
+      ]);
+    trigger.getDynamicValue = mockGetDynamicValue;
+    jest.useFakeTimers({ now: 1730123456789 });
+
+    // Act
+    const results = await trigger.generateSampleEvents({});
+
+    // Assert
+    expect(mockGetDynamicValue).toHaveBeenCalledWith({
+      componentId: 'com.keragon.<%= connectorId %>.getItems',
+      processInputs: '${ {} }',
+      processOutputs: '${ }',
+    });
+    expect(results).toEqual([
+      // TODO
+    ]);
+  });
+
+});

package/assets/templates/add/pollingtrigger/src/components/<%= componentName %>/<%= componentName %>.definition.json.ejs

@@ -0,0 +1,48 @@
+{
+  "id": "<%= componentId %>",
+  "title": "<%= title %>",
+  "description": "<%= desc %>",
+  "type": "trigger",
+  "sdkVersion": "0.0.1"
+  <% if (typeof alert !== 'undefined') { %>
+  ,"alerts": [{
+    "type": "info",
+    "content": "Due to vendor limitations you can have only one polling trigger"
+  }]
+  <% } %>,
+  "poll": {
+    "schedule": {
+      "cron": "*/5 * * * *"
+    },
+    "dedup": {
+      "strategy": "lastTimestamp",
+      "getDedupValue": "${ .item.created_time }"
+    },
+    "poller": {
+      "componentId": "<%= connectorId %>.getItems<TODO set correct component>",
+      "processInputs": "${ { event: .event } }",
+      "processOutputs": "${ . | sort_by(.created_time) | reverse }"
+    }
+  }
+  <% if (typeof inputs !== 'undefined') { %>
+  ,"inputs": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "event"
+    ],
+    "properties": {
+      "event": {
+        "type": "string",
+        "title": "Event",
+        "dynamicEnum": {
+          "componentId": "<%= connectorId %>.get",
+          "processInputs": "${ }",
+          "processOutputs": "${ [.[] | {label: .name, value: .type}] }"
+        }
+      }
+    }
+  }
+  <% } %>
+}

package/assets/templates/add/pollingtrigger/src/components/<%= componentName %>/<%= componentName %>.ts.ejs

@@ -0,0 +1,32 @@
+import {
+  HasSampleEvents,
+  SampleEvent,
+  PollingTrigger,
+  App,
+} from '@keragon/connector-sdk';
+
+export default class <%= firstLetterUpperCase(componentName) %> extends PollingTrigger<App> implements HasSampleEvents {
+
+  async generateSampleEvents({ store: _, ...inputs }: Record<string, unknown>): Promise<SampleEvent[]> {
+    const { a, b, c } = this.validateInputs(inputs);
+    const items = await this.getDynamicValue({
+      componentId: '<%= connectorId %>.getItems<TODO set correct component>',
+      processInputs: `\${ ${JSON.stringify({ a, b, c })} }`,
+      processOutputs: '${ sort_by(.date) | reverse }'
+    });
+    if (!Array.isArray(items)) {
+      throw new Error('items must be an array');
+    }
+    return items.slice(0, 5)
+      .map((i) => ({
+        label: `Sample item ${i}`,
+        value: {
+          data: {
+            body: i,
+            headers: {},
+          }
+        }
+      }));
+  }
+}
+

package/assets/templates/add/pollingtrigger/src/components/<%= componentName %>/index.ts.ejs

@@ -0,0 +1,7 @@
+import definition from './<%= componentName %>.definition.json';
+import <%= firstLetterUpperCase(componentName) %> from './<%= componentName %>';
+
+export default {
+  ctor: <%= firstLetterUpperCase(componentName) %>,
+  definition,
+};

package/assets/templates/add/trigger/__tests__/<%= componentName %>.test.ts.ejs

@@ -0,0 +1,154 @@
+import { CloudEventData } from '@keragon/types';
+import { CloudEvent } from 'cloudevents';
+import app from '../src';
+const { definition, ctor: <%= firstLetterUpperCase(connectorId) %> } = app;
+
+const mockAxiosGet = jest.fn();
+const mockAxiosPost = jest.fn();
+const mockAxiosPut = jest.fn();
+const mockAxiosDelete = jest.fn();
+const mockIsAxiosError = jest.fn();
+jest.mock('axios', () => ({
+  create: jest.fn((defaults) => ({
+    get: mockAxiosGet,
+    post: mockAxiosPost,
+    put: mockAxiosPut,
+    delete: mockAxiosDelete,
+    defaults,
+  })),
+  isAxiosError: jest.fn().mockImplementation(() => (mockIsAxiosError())),
+}));
+
+//Mock Date.now
+const now = 1738876122999;
+jest.useFakeTimers({ now });
+
+const setUpTest = ({
+  store,
+}: {
+  store?: Record<string, unknown>;
+}) => {
+  const <%= connectorId %>: InstanceType<typeof <%= firstLetterUpperCase(connectorId) %>> = new <%= firstLetterUpperCase(connectorId) %>({
+    definition,
+    credentials: {
+      key: 'mockKey',
+      authScheme: {
+        // TODO authScheme
+        id: 'com.keragon.<%= connectorId %>.environments.prod.authSchemes.apiKey',
+      },
+    }
+  });
+
+  const trigger = <%= connectorId %>.constructComponent({ componentId: 'com.keragon.<%= connectorId %>.<%= componentId %>', store });
+  return { <%= connectorId %>, trigger, webhookUrl: 'https://test.com/v1/' };
+};
+
+describe('Component: Trigger com.keragon.<%= connectorId %>.<%= componentId %> should', () => {
+
+  describe('implement configure() and', () => {
+
+    it('register the webhook', async () => {
+      const { trigger, webhookUrl } = setUpTest({});
+
+      // Arrange: Mock request to register the webhook
+      mockAxiosPost.mockResolvedValue({ data: { data: { id: 'mockWebhookId' } } });
+      const inputs = {
+        // TODO
+      }
+
+      // Act
+      const configuredInputs = await trigger.configure(inputs, webhookUrl);
+
+      // Assert
+      expect(mockAxiosPost).toHaveBeenCalledWith('/', {
+        data: {
+        }
+      });
+
+      // Assert that the webhook id, url and secret were stored
+      expect(trigger.store.get('webhookURL')).toEqual('https://test.com/v2/?triggerId=com.keragon.<%= connectorId %>.<%= componentId %>');
+      expect(trigger.store.get('webhookID')).toEqual('mockWebhookId');
+
+      // Assert that the configured inputs are returned
+      expect(configuredInputs).toEqual(inputs);
+    });
+
+    it('deactivate an existing webhook before create a new one', async () => {
+      // Arrange : setup
+      const { trigger, webhookUrl } = setUpTest({
+        store: {
+          webhookURL: 'webhookURL',
+          webhookID: 'mockWebhookId1',
+        }
+      });
+      const inputs = {
+      }
+      // Arrange: Mock request to delete the old webhook
+      mockAxiosDelete.mockResolvedValue({ data: {} });
+      // Arrange: Mock request to create the webhook
+      mockAxiosPost.mockResolvedValue({ data: { data: { id: 'mockWebhookId2' } } });
+
+      // Act
+      await trigger.configure(inputs, webhookUrl);
+
+      // Assert
+      expect(mockAxiosDelete).toHaveBeenCalledWith('/webhooks/mockWebhookId1');
+      expect(mockAxiosPost).toHaveBeenCalledWith('/webhooks', expect.any(Object));
+    });
+
+  });
+
+  describe('implement run() and', () => {
+
+    it('fail if webhook request could not have data', async () => {
+      const { trigger } = setUpTest({
+        store: {}
+      });
+
+      const event = {} as CloudEvent<CloudEventData>;
+
+      await expect(trigger.run({ event })).rejects.toThrow('Component com.keragon.<%= connectorId %>.<%= componentId %> run() received no event payload');
+    });
+
+    it('return passed events', async () => {
+      const { trigger } = setUpTest({
+        store: {}
+      });
+
+      const mockEvent = {
+      }
+
+      const event = { data: { body: { events: [mockEvent] } } } as unknown as CloudEvent<CloudEventData>;
+
+      const output = await trigger.run({ event });
+
+      expect(output).toEqual({ result: [mockEvent] });
+    });
+  });
+
+  describe('implement deactivate() and', () => {
+
+    it('deletes the webhook', async () => {
+      const { trigger } = setUpTest({
+        store: {
+          webhookID: 'mockWebhookId',
+        }
+      });
+
+      // Arrange: Mock request to unregister the webhook
+      mockAxiosDelete.mockResolvedValue({});
+
+      // Act
+      await trigger.deactivate?.();
+
+      // Assert that the webhook was registered with the correct args
+      expect(mockAxiosDelete).toHaveBeenCalledWith('/webhooks/mockWebhookId');
+
+      // Assert that the store is cleared
+      expect(trigger.store.get('webhookURL')).toBeUndefined()
+      expect(trigger.store.get('webhookID')).toBeUndefined()
+    });
+
+  });
+
+});

package/assets/templates/add/trigger/src/components/<%= componentName %>/<%= componentName %>.definition.json.ejs

@@ -0,0 +1,42 @@
+{
+  "id": "<%= componentId %>",
+  "title": "<%= title %>",
+  "description": "<%= desc %>",
+  "type": "trigger",
+  "sdkVersion": "0.0.1"
+  <% if (typeof alert !== 'undefined') { %>
+  ,"alerts": [{
+    "type": "info",
+    "content": "Please follow the [article](https://go.keragon.com/<%= componentName %>) to set up the trigger"
+  }]
+  <% } %>
+  <% if (typeof http !== 'undefined') { %>
+  ,"request": {
+    "config": {
+      "method": "get",
+      "url": "/"
+    }
+  }
+  <% } %>
+  <% if (typeof inputs !== 'undefined') { %>
+  ,"inputs": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "event"
+    ],
+    "properties": {
+      "event": {
+        "type": "string",
+        "title": "Event",
+        "dynamicEnum": {
+          "componentId": "<%= connectorId %>.get",
+          "processInputs": "${ }",
+          "processOutputs": "${ [.[] | {label: .name, value: .type}] }"
+        }
+      }
+    }
+  }
+  <% } %>
+}

package/assets/templates/add/trigger/src/components/<%= componentName %>/<%= componentName %>.ts.ejs

@@ -0,0 +1,76 @@
+import {
+  HasSampleEvents,
+  SampleEvent,
+  extractErrorMessage,
+  RunFunctionReturnType,
+  RunFunctionArgs,
+  <%= http ? 'HttpApp' : 'App' %>,
+  <%= http ? 'HttpComponent' : 'Component' %>,
+} from '@keragon/connector-sdk';
+
+const WEBHOOK_ID = 'webhookID';
+const WEBHOOK_URL = 'webhookURL';
+
+export default class <%= firstLetterUpperCase(componentName) %> extends <%- http ? 'HttpComponent<HttpApp>' : 'Component<App>' %> implements HasSampleEvents {
+
+  override async configure(inputs: Record<string, unknown> = {}, webhookURL: string, ..._rest: string[]) {
+    if (this.store.get(WEBHOOK_ID)) {
+      await this.deactivate();
+    }
+    const configuredInputs = await super.configure(inputs);
+    const url = new URL(webhookURL);
+    url.pathname = url.pathname.replace('/v1/', '/v2/');
+    url.searchParams.set('triggerId', this.definition.id.toLowerCase());
+    this.store.set(WEBHOOK_URL, url.toString());
+    this.store.set(WEBHOOK_URL, url.toString());
+    
+    const client = await this.app.getClient();
+    try {
+      const { data: { id } } = await client.post('/', {});
+      this.store.set(WEBHOOK_URL, webhookURL);
+      this.store.set(WEBHOOK_ID, id);
+      return configuredInputs;
+    } catch (error) {
+      throw new Error(`Failed to configure ${this.definition.id} because ${extractErrorMessage(error)}.`);
+    }
+  }
+
+  override async run({ event }: RunFunctionArgs): Promise<RunFunctionReturnType> {
+    const componentId = this.definition.id;
+    if (!event?.data)
+      throw new Error(`Component ${componentId} run() received no event payload`);
+    const data = event.data.body;
+    return { result: data };
+  }
+
+  override async deactivate() {
+    try {
+      this.store.delete(WEBHOOK_URL);
+    } catch (error) {
+      throw new Error(`Failed to deactivate "${this.definition.id}" because ${extractErrorMessage(error)}`);
+    }
+  }
+
+  async generateSampleEvents({ store: _, ...inputs }: Record<string, unknown>): Promise<SampleEvent[]> {
+    const { a, b, c } = this.validateInputs(inputs);
+    const items = await this.getDynamicValue({
+      componentId: '<%= connectorId %>.getItems<TODO set correct component>',
+      processInputs: `\${ ${JSON.stringify({ a, b, c })} }`,
+      processOutputs: '${ sort_by(.date) | reverse }'
+    });
+    if (!Array.isArray(items)) {
+      throw new Error('items must be an array');
+    }
+    return items.slice(0, 5)
+      .map((i) => ({
+        label: `Sample item ${i}`,
+        value: {
+          data: {
+            body: i,
+            headers: {},
+          }
+        }
+      }));
+  }
+}
+

package/assets/templates/add/trigger/src/components/<%= componentName %>/index.ts.ejs

@@ -0,0 +1,7 @@
+import definition from './<%= componentName %>.definition.json';
+import <%= firstLetterUpperCase(componentName) %> from './<%= componentName %>';
+
+export default {
+  ctor: <%= firstLetterUpperCase(componentName) %>,
+  definition,
+};

package/assets/templates/create/connector/README.md.ejs

@@ -0,0 +1 @@
+# <%= name %> connector

package/assets/templates/create/connector/keragon.json.ejs

@@ -0,0 +1,3 @@
+{
+  "name": "<%= name %>"
+}

package/assets/templates/create/connector/package.json.ejs

@@ -0,0 +1,18 @@
+{
+  "name": "@keragonhq/<%= name %>",
+  "version": "0.0.1",
+  "description": "Keragon's built-in <%= firstLetterUpperCase(name) %> app",
+  "main": "index.js",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@keragon/connector-sdk": "0.0.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/assets/templates/create/connector/src/<%= name %>.definition.json.ejs

@@ -0,0 +1,10 @@
+{
+  "id": "com.keragon.<%= name %>",
+  "title": "<%= firstLetterUpperCase(name) %>",
+  "tags": <%- JSON.stringify(tags ?? []) %>,
+  "icon": "/assets/<%= name %>.svg",
+  "description": "<%= desc %>",
+  "version": "0.0.1",
+  "environments": [
+  ]
+}

package/assets/templates/create/connector/src/components/index.ts.ejs

@@ -0,0 +1,2 @@
+export default [
+];

package/assets/templates/create/connector/src/index.ts.ejs

@@ -0,0 +1,9 @@
+import {
+  <%= http ? 'createHttpAppDescriptor' : 'createAppDescriptor' %>
+} from '@keragon/connector-sdk';
+import components from './components';
+import definition from './<%= name %>.definition.json';
+
+export default <%= http ? 'createHttpAppDescriptor' : 'createAppDescriptor' %> ({
+  definition: { ...definition, components },
+});