n8n-nodes-job-availability

n8n-nodes-job-availability is a declarative community node for a self-hosted Job Availability service. It observes public job postings and manages durable availability runs while keeping schedules, loops, branching, retries, recovery, and notifications visible in the workflow.

Maturity: version 0.2.1 self-hosted npm preview. Declarative routing, package checks, and isolated workflow integration pass in fresh n8n 2.0.0, 2.23.2, and 2.36.7 environments. Creator Portal review is a separate gate, so the package must not be described as verified, available on n8n Cloud, or approved for canonical product cutover until those gates are complete.

See the public roadmap for release gates and planned availability. Changes are recorded in the changelog; contribution and security procedures are documented in CONTRIBUTING.md and SECURITY.md.

Compatibility

Minimum supported n8n runtime: 2.0.0. Package loading is confirmed on n8n 2.0.0, 2.23.2, and 2.36.7. The build-time type surface resolves n8n-workflow 2.37.0, and package checks run on Node.js 22.22.0 and Node.js 24.19.0.

The package has no runtime dependencies. Its only peer dependency is n8n-workflow: "*".

Community availability

Version 0.2.1 is distributed through the public npm registry for unverified, self-hosted n8n use. Discovery from the nodes panel and n8n Cloud installation additionally require review through the n8n Creator Portal.

The companion Job Availability API is distributed separately and can be self-hosted on a private machine or Docker network. The node and API repositories together support a complete controlled self-hosted evaluation. A loopback or private-network service is not reachable from n8n Cloud.

Installation

Deploy the companion API by following its private self-hosting instructions. Then, on a self-hosted n8n instance, open Settings > Community Nodes, select Install, and enter:

n8n-nodes-job-availability

Restart n8n if your deployment does not reload community packages automatically.

From source

Build and validate the package from a clean checkout:

npm ci
npm run validate
npm pack

Install the generated tarball in the nodes directory below the self-hosted n8n user folder, then restart n8n.

To uninstall, remove n8n-nodes-job-availability from that nodes directory, reinstall its remaining dependencies, and restart n8n. Uninstalling the node does not delete service-side availability data.

Configure credentials

The node uses one Job Availability API credential:

• Base URL: root URL of the local service, normally http://127.0.0.1:5002 outside containers or http://host.docker.internal:5002 from a macOS container.
• Service Token: operator token generated by the service. The field is masked and sent only as a bearer token.

Generate the service token from the service project and store it in the approved local secret mechanism. Paste the same value into the n8n credential. Use Test credential to call GET /v1/credentials/test; the response contains readiness and version information but no product data or token.

Use HTTPS when traffic crosses a trusted single-host boundary. Do not include user information in the Base URL. Native credential URL validation provides syntax assistance; the authenticated credential-test endpoint is the enforceable connectivity boundary for this private, configurable service origin.

Token rotation is a maintenance operation: stop the service, generate and configure a replacement, update the n8n credential, restart the service, and test the credential. The prior token must then return 401. Revocation removes or replaces the configured service secret.

Resources and operations

Posting:

• Observe: submits a platform, URL, expected title, and optional company for one stateless observation. It does not create a canonical product job.

Availability Run:

• Create: creates a durable run for 1–100 explicit existing job IDs.
• Create Scheduled: accepts only an idempotency key; the service fixes the trigger to schedule, snapshots the canonical inventory, and fails when it is empty or above 1,000 jobs.
• Get: returns bounded run status, counts, at most 100 pending job IDs, and errors.
• Finalize: finalizes a run only after no jobs remain pending.
• Cancel: makes cancellation terminal. Recovery creates a new run.

Job:

• Check Availability: checks one registered job inside one durable run.
• Get Availability: returns the current bounded job state.

Observe, Create, and Create Scheduled send contract schema_version: 1. Every POST, including stateless Observe, requires an idempotency key. Use stable keys within a workflow execution and distinct keys for distinct operations or job IDs. When the n8n runtime exposes $execution.id to declarative request defaults, the node sends it as the privacy-safe X-N8N-Execution-Id correlation header. n8n 2.0.0 omits this optional header; n8n 2.23.2 and 2.36.7 include it. The service must create usable correlation independently and must not depend on this header.

Use as an AI Agent tool

The node can be connected to an n8n AI Agent as an app tool. The workflow author remains responsible for the authority boundary:

• Fix Resource and Operation in the tool configuration; do not let a prompt choose them.
• Delegate only the fields the model needs for that action. Never delegate the Base URL, service token, or idempotency key.
• Use a workflow-derived idempotency key such as {{$execution.id + ':ai-tool-observe'}}.
• Prefer Posting > Observe for demonstrations because it performs one bounded observation without creating a canonical product job.
• Require human review before enabling durable mutations such as run creation, checks, finalization, or cancellation in an agent-driven workflow.

The service remains the enforceable authentication, network, idempotency, and state boundary. Tool use does not give the model direct access to the service token or add any node-side filesystem, environment, or subprocess capability.

Output, limits, and privacy

The node returns the service JSON response without local classification or persistence logic. The service bounds exposed source evidence to 20 entries and the five fields platform, outcome, evidence_code, checked_at, and http_status, plus sources_truncated.

The node does not access the host filesystem or environment, run subprocesses, or import runtime SDKs. It does not expose URLs, page bodies, request headers, workflow payloads, or credentials in output. n8n processes each input item independently and preserves item lineage through its declarative routing engine.

Errors and recovery

The service returns RFC 9457-compatible problem documents. Important codes include invalid_request, authentication_failed, not_found, payload_too_large, unsupported_media_type, idempotency_conflict, no_jobs_available, inventory_limit_exceeded, run_cancelled, run_has_pending_jobs, run_terminal, job_not_checkable, rate_limited, internal_error, and service_unavailable.

An inconclusive posting result is a successful domain response, not an API failure. A cancelled run is never resumed; create a new run identity. See operations for diagnosis and rollback procedures.

Example workflows

• Manual posting observation
• Daily durable availability run
• AI Agent posting observation tool

All workflows contain synthetic values or delegated placeholders and no credential secret. The daily workflow refreshes the bounded RunDTO after each pending-ID window until no jobs remain, so a single scheduled run can cover the full service-owned inventory without exposing an inventory-list operation. The agent example fixes Posting > Observe and its idempotency key while delegating only the posting details. Import the examples, select local credentials, and keep them inactive until the service configuration is verified.

Development

npm ci
npm run lint
npm run typecheck
npm run typecheck:test
npm run build
npm run scanner:local
npm test
npm run package:inspect

The committed API contract fixture binds the node to Job Availability API v1 and records the approved OpenAPI, public-schema, fixture-manifest, and 65-case corpus hashes. Contract drift requires an intentional fixture and test update; runtime source remains independent of the service implementation.

Package design, release gates, and expected workflows are documented in operations, security evidence, and workflow evidence.

License

MIT. See LICENSE.md.