Initial code commit

Author: cmuench

.agents/credentials.md

@@ -0,0 +1,115 @@
+# Credentials
+
+Credentials are used to authenticate with external services and store
+sensitive values. They are encrypted at rest.
+
+## Credential class anatomy
+Credentials classes have:
+- `name` – machine name (used in nodes' `credentials` array)
+- `displayName` – human-readable label in the UI
+- `properties` – parameters (similar types to node properties)
+Sensitive properties should set `typeOptions.password = true`
+
+## Example
+Simplified WordPress example:
+```typescript
+export class WordpressApi implements ICredentialType {
+  name = 'wordpressApi';
+  displayName = 'Wordpress API';
+  documentationUrl = 'wordpress';
+
+  properties: INodeProperties[] = [
+    {
+      displayName: 'Username',
+      name: 'username',
+      type: 'string',
+      default: '',
+    },
+    {
+      displayName: 'Password',
+      name: 'password',
+      type: 'string',
+      typeOptions: {
+        password: true,
+      },
+      default: '',
+    },
+    {
+      displayName: 'Wordpress URL',
+      name: 'url',
+      type: 'string',
+      default: '',
+      placeholder: 'https://example.com',
+    },
+  ];
+
+  authenticate: IAuthenticateGeneric = {
+    type: 'generic',
+    properties: {
+      auth: {
+        username: '={{$credentials.username}}',
+        password: '={{$credentials.password}}',
+      },
+    },
+  };
+
+  test: ICredentialTestRequest = {
+    request: {
+      baseURL: '={{$credentials?.url}}/wp-json/wp/v2',
+      url: '/users',
+      method: 'GET',
+    },
+  };
+}
+```
+
+## Notes
+- `test` describes how to check if credentials are valid to show a
+  message to the user in the UI
+  - Not strictly required, but strongly recommended.
+- `authenticate` describes how to modify requests for declarative-style
+  nodes and the HTTP Request node.
+
+## Custom authenticate function
+You can also use a custom authenticate function:
+```typescript
+authenticate: IAuthenticate = async (credentials, requestOptions) => {
+  const values = (credentials.headers as { values: Array<{ name: string; value: string }> }).values;
+
+  const headers = values.reduce((acc, cur) => {
+    acc[cur.name] = cur.value;
+    return acc;
+  }, {} as Record<string, string>);
+
+  return {
+    ...requestOptions,
+    headers: {
+      ...requestOptions.headers,
+      ...headers,
+    },
+  };
+};
+```
+
+## OAuth2 credentials
+For services using OAuth2:
+- You usually do not need to define `test` or `authenticate` explicitly.
+- Instead, create credentials that extend `oAuth2Api`:
+```typescript
+export class MyServiceOAuth2Api implements ICredentialType {
+  name = 'myServiceOAuth2Api';
+  displayName = 'My Service OAuth2 API';
+  extends = ['oAuth2Api'];
+
+  properties: INodeProperties[] = [
+    // Add only the extra properties your service needs,
+    // e.g. scopes, custom URLs, etc.
+  ];
+}
+```
+- The base `oAuth2Api` handles the generic OAuth2 flow.
+- When allowing users to specify scopes in a custom OAuth2 credential,
+  make sure to follow n8n's internal rules (see n8n docs).
+- If you want to define scopes that the credentials will request, add a
+  property with `name: 'scope'`, `type: 'hidden'` and `default` field
+  that has your desired scopes

.agents/nodes-declarative.md

@@ -0,0 +1,103 @@
+# Declarative nodes
+
+Preferred for most integrations that simply call external APIs.
+
+Also read `.agents/nodes.md` for shared node anatomy and conventions.
+
+## When to use
+- The integration is mostly simple HTTP/REST requests and responses
+- You can express the behavior by mapping parameters to
+  URL/query/body/headers
+
+If you need multiple dependent API calls, complex control flow, or heavy
+transformations, use programmatic-style instead (see
+`.agents/nodes-programmatic.md`).
+
+## What you define
+- Node `properties` (parameters)
+- `requestDefaults` (base URL, default headers)
+- `routing` on parameters and operations:
+  - Where to send the request (URL, method)
+  - How to map parameters to query/body/headers
+  - Optional pre-send and post-receive transformations
+
+## requestDefaults
+```typescript
+requestDefaults: {
+  baseURL: 'https://api.nasa.gov',
+  headers: {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+  },
+},
+```
+
+## Parameter routing
+Example parameter with `routing`:
+```typescript
+{
+  displayName: 'Rover Name',
+  description: 'Choose which Mars Rover to get a photo from',
+  required: true,
+  name: 'roverName',
+  type: 'options',
+  options: [
+    { name: 'Curiosity', value: 'curiosity' },
+    { name: 'Opportunity', value: 'opportunity' },
+    { name: 'Perseverance', value: 'perseverance' },
+    { name: 'Spirit', value: 'spirit' },
+  ],
+  routing: {
+    request: {
+      method: 'GET',
+      url: '=/mars-photos/api/v1/rovers/{{$value}}/photos',
+    },
+  },
+  default: 'curiosity',
+  displayOptions: {
+    show: {
+      resource: ['marsRoverPhotos'],
+    },
+  },
+}
+```
+
+## Post-receive transformations
+You can modify response data with `routing.output.postReceive`:
+```typescript
+postReceive: [
+  {
+    type: 'setKeyValue',
+    properties: {
+      name: '={{$responseItem.modelName}}',
+      description: '={{$responseItem.modelArn}}',
+      value: '={{$responseItem.modelId}}',
+    },
+  },
+  {
+    type: 'sort',
+    properties: {
+      key: 'name',
+    },
+  },
+  async function (
+    this: IExecuteSingleFunctions,
+    data: INodeExecutionData[],
+    response: IN8nHttpFullResponse,
+  ): Promise<INodeExecutionData[]> {
+    // Custom transformation if needed
+    return data;
+  },
+]
+```
+
+## Pre-send transformations
+You can also use `routing.send.preSend` to change the request before
+sending (e.g. add custom headers or body transformations).
+
+## Guidelines
+- Prefer **declarative transformations** like `setKeyValue`, `sort`, etc
+  (there are other transformations that are not in the example).
+- Only add custom functions when necessary.
+- Declarative-style nodes only support **light versioning** (not full
+  versioning). See `.agents/versioning.md` for details.

.agents/nodes-programmatic.md

@@ -0,0 +1,76 @@
+# Programmatic nodes
+
+Programmatic-style nodes implement an `execute` method and have full
+control over HTTP calls, loops, transformations, etc.
+
+Also read `.agents/nodes.md` for shared node anatomy and conventions.
+
+## When to use
+- You need multiple dependent API calls per node execution.
+- You need complex transformations or branching logic.
+- The API doesn't map cleanly into simple "one request per item"
+  patterns.
+
+If the integration is mostly simple HTTP/REST requests, prefer
+declarative-style instead (see `.agents/nodes-declarative.md`).
+
+If you choose programmatic-style, briefly explain **why**
+declarative-style won't work for this particular node.
+
+## Canonical execute pattern
+```typescript
+async execute(
+  this: IExecuteFunctions,
+): Promise<INodeExecutionData[][]> {
+  const items = this.getInputData();
+  const returnData: INodeExecutionData[] = [];
+
+  for (let i = 0; i < items.length; i++) {
+    try {
+      const resource = this.getNodeParameter('resource', i) as string;
+      const operation = this.getNodeParameter('operation', i) as string;
+
+      // Implement logic based on resource + operation
+      // Use this.helpers.httpRequest / httpRequestWithAuthentication, etc.
+      const responseData = {};
+
+      returnData.push({
+        json: responseData,
+        pairedItem: { item: i },
+      });
+    } catch (error) {
+      if (this.continueOnFail()) {
+        returnData.push({
+          json: {
+            error: (error as Error).message,
+          },
+          pairedItem: { item: i },
+        });
+        continue;
+      }
+
+      // Implement a check to see what error we have
+      const isApiError = true;
+      // Use NodeApiError for API-related errors
+      if (isApiError) {
+        throw new NodeApiError(this.getNode(), error as Error, { itemIndex: i });
+      }
+
+      // Use NodeOperationError for configuration/validation errors
+      throw new NodeOperationError(this.getNode(), error as Error, { itemIndex: i });
+    }
+  }
+
+  return [returnData];
+}
+```
+
+## Guidelines
+- Always get input items via `this.getInputData()`
+- Pass the correct item index as the second argument to
+  `getNodeParameter`
+- Handle errors using `NodeApiError` (for API failures) and
+  `NodeOperationError` (for operational/validation errors)
+- Support `continueOnFail()` to allow workflows to proceed when possible
+- Programmatic-style nodes support both **light and full versioning**.
+  See `.agents/versioning.md` for details.