EDC Connector Client 👩‍🚀

A HTTP client to communicate with the EDC Connector for Node.js and the browser.

_{Built with ❤️ at Think-it.}

Abstract

The EDC Connector is a framework for a sovereign, inter-organizational data exchange. It provides low-level primitives to allow network participants to expose and consume offers.

This project aims to increase the level of abstraction, bringing the low-level HTTP API to mid-level developers by providing an HTTP Client which is thoroughly tested and fully type-safe.

Similarly to the EDC Connector, this library is at its early stage. It aims to maintain compatibility with the latest version of the Connector. API specification can be found on Management Api Openapi UI

Compatibility matrix

Client	API
0.8.x 0.7.x	Management v3 Catalog v1-alpha

Client	EDC
0.6.x	0.7.x
0.5.x 0.4.x	0.6.x
0.3.0	0.5.0
0.2.1	0.4.1
0.2.0	0.2.0

Usage

Install via npm or yarn

npm install @think-it-labs/edc-connector-client

yarn add @think-it-labs/edc-connector-client

Once installed, clients can be instanciated by construcing a EdcConnectorClient.

With internal context

The standard way of using the client would be associating it with a connector, for doing that it can be instantiated through the EdcConnectorClient.Builder

import { EdcConnectorClient } from "@think-it-labs/edc-connector-client"

const client = new EdcConnectorClient.Builder()
  .apiToken("123456")
  .managementUrl("https://edc.think-it.io/management")
  .publicUrl("https://edc.think-it.io/public")
  .build();

At this point the calls can be made against the specified connector:

const result = await client.management.assets.create({
  properties: {
      "name": "asset name",
      "key": "any value"
  },
  dataAddress: {
    name: "An HTTP address",
    baseUrl: "https://example.com/",
    type: "HttpData",
    path: "/some-data",
    contentType: "application/json",
    method: "GET",
  },
});

Without internal context

A single connector instance can be used to call multiple connectors, just creating different contexts and passing them to the specific call.

The connector can be instantiated directly without the builder:

import { EdcConnectorClient } from "@think-it-labs/edc-connector-client"

const client = new EdcConnectorClient();

Context objects can be created with a createContext call:

const context = client.createContext("123456", {
  default: "https://edc.think-it.io/api",
  management: "https://edc.think-it.io/management",
  protocol: "https://edc.think-it.io/protocol",
  public: "https://edc.think-it.io/public",
  control: "https://edc.think-it.io/control",
});

And the context can be passed to every call as latest argument:

const result = await client.management.assets.create(context, {
  asset: {
    properties: {
      "name": "asset name",
      "key": "any value"
    },
    dataAddress: {
      name: "An HTTP address",
      baseUrl: "https://example.com/",
      type: "HttpData",
      path: "/some-data",
      contentType: "application/json",
      method: "GET",
    },
  }
});

Extending the Client with Custom Controllers

The client can be extended with custom controllers using the use method. This feature allows you to add your own functionality while maintaining type safety through the EdcController base class. The extension system is designed to be middleware-like, where each controller is lazily instantiated when accessed.

Here's how to use it:

import { EdcConnectorClient, EdcController } from "@think-it-labs/edc-connector-client"

// Define your custom controller by extending EdcController
class CustomController extends EdcController {
  constructor(inner: any, context: any) {
    super(inner, context);
  }

  async customMethod() {
    // Your custom implementation
    // You have access to this.inner and this.context
  }
}

// Extend the client with your custom controller
const client = new EdcConnectorClient.Builder()
  .apiToken("123456")
  .managementUrl("https://edc.think-it.io/management")
  .use("custom", CustomController)  // Add your custom controller
  .build();

// Use your custom controller
await client.custom.customMethod();

The use method takes two parameters:

1. A string property name that will be used to access your controller
2. A class that extends EdcController

The EdcController base class provides:

• A standardized way to construct controllers
• Access to the client's inner functionality
• Access to the client's context for making API calls

TypeScript will properly type your custom controller and its methods, ensuring type safety throughout your application. You can also explicitly type your extended client:

type MyExtendedClient = EdcConnectorClientType<{
  custom: CustomController;
}>;

const client: MyExtendedClient = new EdcConnectorClient.Builder()
  .use("custom", CustomController)
  .build();

Error handling

All API methods are type, and error-safe, which means arguments are fully typed with TypeScript, and thrown errors are always EdcConnectorClientError instances. This error safety level is achieved using the TypedError library.

import { EdcConnectorClientError, EdcConnectorClientErrorType } from "@think-it-labs/edc-connector-client"

try {

  // perform async EdcConnectorClient actions

} catch(error) {
  if (error instanceof EdcConnectorClientError) {
    switch (error.type) {
      case EdcConnectorClientErrorType.Duplicate: {
        // handle duplicate error
      }

      // ...

      case EdcConnectorClientErrorType.Unknown:
      default: {
        // red alert: unknown behaviour
      }
    }
  }
}

Note if you encounter an Unknown error you should report this behavior along steps to reproduce it. Unknown behaviors are unwanted and must be fixed asap.

Development

docker compose is used to run the development environment. It runs two connectors with capabilities described in the gradle configuration file.

Please, adhere to the CONTRIBUTING guidelines when suggesting changes in this repository.

Release

The release github action workflow takes care of release.

License

Copyright 2022-2023 Think.iT GmbH.

Licensed under the Apache License, Version 2.0. Files in the project may not be copied, modified, or distributed except according to those terms.