Skip to content

Latest commit

 

History

History
689 lines (518 loc) · 34.2 KB

README.md

File metadata and controls

689 lines (518 loc) · 34.2 KB
Raw

Version Downloads/week Build Status License Greenkeeper badge Codecov Coverage

Adobe I/O Events Lib

Installing

$ npm install @adobe/aio-lib-events

Usage

  1. Initialize the SDK
const sdk = require('@adobe/aio-lib-events')

async function sdkTest() {
  //initialize sdk
  const client = await sdk.init('<organization id>', 'x-api-key', '<valid auth token>', '<options>')
}
  1. Call methods using the initialized SDK
const sdk = require('@adobe/aio-lib-events')

async function sdkTest() {
  // initialize sdk
  const client = await sdk.init('<organization id>', 'x-api-key', '<valid auth token>', '<options>')

  // call methods
  try {
    // get profiles by custom filters
    const result = await client.getSomething({})
    console.log(result)

  } catch (e) {
    console.error(e)
  }
}
  1. Using the poller for journalling
const sdk = require('@adobe/aio-lib-events')

async function sdkTest() {
  // initialize sdk
  const client = await sdk.init('<organization id>', 'x-api-key', '<valid auth token>', '<http options>')
  // get the journalling observable
  const journalling = client.getEventsObservableFromJournal('<journal url>', '<journalling options>')
  // call methods
  const subscription = journalling.subscribe({
    next: (v) => console.log(v), // Action to be taken on event
    error: (e) => console.log(e), // Action to be taken on error
    complete: () => console.log('Complete') // Action to be taken on complete
  })
  
  // To stop receiving events from this subscription based on a timeout
  setTimeout(() => subscription.unsubscribe(), <timeout in ms>)
}

One observable can have multiple subscribers. Each subscription can be handled differently. For more details on using the poller for Journalling check getEventsObservableFromJournal

Classes

EventsCoreAPI

This class provides methods to call your Adobe I/O Events APIs. Before calling any method initialize the instance by calling the init method on it with valid values for organizationId, apiKey, accessToken and optional http options such as timeout and max number of retries

Functions

init(organizationId, apiKey, accessToken, [httpOptions]) ⇒ Promise.<EventsCoreAPI>

Returns a Promise that resolves with a new EventsCoreAPI object.

Typedefs

EventsCoreAPIOptions : object
ProviderFilterOptions : object
ProviderOptions : object
ProviderInputModel : object
EventMetadataInputModel : object
EventsOfInterest : object
RegistrationCreateModel : object
RegistrationUpdateModel : object
Page : object
EventsJournalOptions : object
EventsJournalPollingOptions : object

EventsCoreAPI

This class provides methods to call your Adobe I/O Events APIs. Before calling any method initialize the instance by calling the init method on it with valid values for organizationId, apiKey, accessToken and optional http options such as timeout and max number of retries

Kind: global class

eventsCoreAPI.httpOptions

Http options {retries, timeout}

Kind: instance property of EventsCoreAPI

eventsCoreAPI.organizationId

The organization id from your integration

Kind: instance property of EventsCoreAPI

eventsCoreAPI.apiKey

The api key from your integration

Kind: instance property of EventsCoreAPI

eventsCoreAPI.accessToken

The JWT Token for the integration with IO Management API scope

Kind: instance property of EventsCoreAPI

eventsCoreAPI.init(organizationId, apiKey, accessToken, [httpOptions]) ⇒ Promise.<EventsCoreAPI>

Initialize SDK.

Kind: instance method of EventsCoreAPI
Returns: Promise.<EventsCoreAPI> - returns object of the class EventsCoreAPI

Param Type Description
organizationId string The organization id from your integration
apiKey string The api key from your integration
accessToken string JWT Token for the integration with IO Management API scope
[httpOptions] EventsCoreAPIOptions Options to configure API calls

eventsCoreAPI.getAllProviders(consumerOrgId, providerOptions) ⇒ Promise.<object>

Fetch all the providers

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Returns list of providers for the org

Param Type Description
consumerOrgId string Consumer Org Id from the console
providerOptions ProviderOptions Provider options

eventsCoreAPI.getProvider(providerId, [fetchEventMetadata]) ⇒ Promise.<object>

Fetch a provider

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Returns the provider specified by the provider id

Param Type Default Description
providerId string The id that uniquely identifies the provider to be fetched
[fetchEventMetadata] boolean false Set this to true if you want to fetch the associated eventmetadata of the provider

eventsCoreAPI.createProvider(consumerOrgId, projectId, workspaceId, body) ⇒ Promise.<object>

Create a new provider given the provider details

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Returns the details of the provider created

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
body ProviderInputModel Json data that describes the provider

eventsCoreAPI.updateProvider(consumerOrgId, projectId, workspaceId, providerId, body) ⇒ Promise.<object>

Update a provider given the id and provider details

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Returns the details of the provider updated

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
providerId string The id that uniquely identifies the provider to be updated
body ProviderInputModel Json data that describes the provider

eventsCoreAPI.deleteProvider(consumerOrgId, projectId, workspaceId, providerId) ⇒ Promise.<object>

Delete a provider given the id

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Returns an empty object if the deletion was successful

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
providerId string The id that uniquely identifies the provider to be deleted

eventsCoreAPI.getProviderMetadata() ⇒ Promise.<object>

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Returns the list of all entitled provider metadata for the org

eventsCoreAPI.getAllEventMetadataForProvider(providerId) ⇒ Promise.<object>

Get all event metadata for a provider

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - List of all event metadata of the provider

Param Type Description
providerId string The id that uniquely identifies the provider whose event metadata is to be fetched

eventsCoreAPI.getEventMetadataForProvider(providerId, eventCode) ⇒ Promise.<object>

Get an event metadata for given provider and event code

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Event metadata that corresponds to the specified event code

Param Type Description
providerId string The id that uniquely identifies the provider whose event metadata is to be fetched
eventCode string The specific event code for which the details of the event metadata is to be fetched

eventsCoreAPI.createEventMetadataForProvider(consumerOrgId, projectId, workspaceId, providerId, body) ⇒ Promise.<object>

Create an event metadata for a provider

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Details of the event metadata created

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
providerId string provider for which the event metadata is to be added
body EventMetadataInputModel Json data that describes the event metadata

eventsCoreAPI.updateEventMetadataForProvider(consumerOrgId, projectId, workspaceId, providerId, eventCode, body) ⇒ Promise.<object>

Update the event metadata for a provider

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Details of the event metadata updated

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
providerId string provider for which the event metadata is to be updated
eventCode string eventCode of the event metadata to be updated
body EventMetadataInputModel Json data that describes the event metadata

eventsCoreAPI.deleteEventMetadata(consumerOrgId, projectId, workspaceId, providerId, eventCode) ⇒ Promise.<object>

Delete an event metadata of a provider

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Empty object if deletion was successful

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
providerId string provider for which the event metadata is to be updated
eventCode string eventCode of the event metadata to be updated

eventsCoreAPI.deleteAllEventMetadata(consumerOrgId, projectId, workspaceId, providerId) ⇒ Promise.<object>

Delete all event metadata of a provider

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Empty object if deletion was successful

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
providerId string provider for which the event metadata is to be updated

eventsCoreAPI.createRegistration(consumerOrgId, projectId, workspaceId, body) ⇒ Promise.<object>

Create a webhook or journal registration

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Details of the webhook/journal registration created

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
body RegistrationCreateModel Json data contains details of the registration

eventsCoreAPI.updateRegistration(consumerOrgId, projectId, workspaceId, registrationId, body) ⇒ Promise.<object>

Update a webhook or journal registration

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Details of the webhook/journal registration to be updated

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
registrationId string Registration id whose details are to be fetched
body RegistrationUpdateModel Json data contains details of the registration

eventsCoreAPI.getRegistration(consumerOrgId, projectId, workspaceId, registrationId) ⇒ Promise.<object>

Get registration details for a given registration

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Details of the webhook/journal registration

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
registrationId string Registration id whose details are to be fetched

eventsCoreAPI.getAllRegistrationsForWorkspace(consumerOrgId, projectId, workspaceId) ⇒ Promise.<object>

Get all registration details for a workspace

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - List of all webhook/journal registrations

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console

eventsCoreAPI.getAllRegistrationsForOrg(consumerOrgId, [page]) ⇒ Promise.<object>

Get all registration details for an org

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Paginated response of all webhook/journal registrations for an org

Param Type Description
consumerOrgId string Consumer Org Id from the console
[page] Page page size and page number

eventsCoreAPI.deleteRegistration(consumerOrgId, projectId, workspaceId, registrationId) ⇒ Promise.<object>

Delete webhook registration

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - Empty object if deletion was successful

Param Type Description
consumerOrgId string Consumer Org Id from the console
projectId string Project Id from the console
workspaceId string Workspace Id from the console
registrationId string Id of the registration to be deleted

eventsCoreAPI.publishEvent(cloudEvent) ⇒ Promise.<string>

Publish Cloud Events

Event publishers can publish events to the Adobe I/O Events using this SDK. The events should follow Cloud Events 1.0 specification: https://github.com/cloudevents/spec/blob/v1.0/spec.md. As of now, only application/json is accepted as the content-type for the "data" field of the cloud event. If retries are set, publish events are retried on network issues, 5xx and 429 error response codes.

Kind: instance method of EventsCoreAPI
Returns: Promise.<string> - Returns OK/ undefined in case of success and error in case of failure

Param Type Description
cloudEvent object Object to be published to event receiver in cloud event format

eventsCoreAPI.getEventsFromJournal(journalUrl, [eventsJournalOptions], [fetchResponseHeaders]) ⇒ Promise.<object>

Get events from a journal.

Kind: instance method of EventsCoreAPI
Returns: Promise.<object> - with the response json includes events and links (if available)

Param Type Description
journalUrl string URL of the journal or 'next' link to read from (required)
[eventsJournalOptions] EventsJournalOptions Query options to send with the URL
[fetchResponseHeaders] boolean Set this to true if you want to fetch the complete response headers

eventsCoreAPI.getEventsObservableFromJournal(journalUrl, [eventsJournalOptions], [eventsJournalPollingOptions]) ⇒ Observable

getEventsObservableFromJournal returns an RxJS Observable

One can go through the extensive documentation on RxJS in order to learn more and leverage the various RxJS Operators to act on emitted events.

Kind: instance method of EventsCoreAPI
Returns: Observable - observable to which the user can subscribe to in order to listen to events

Param Type Description
journalUrl string URL of the journal or 'next' link to read from (required)
[eventsJournalOptions] EventsJournalOptions Query options to send with the Journal URL
[eventsJournalPollingOptions] EventsJournalPollingOptions Journal polling options

eventsCoreAPI.verifyDigitalSignatureForEvent(event, recipientClientId, signatureOptions) ⇒ boolean

Authenticating events by verifying digital signature

Kind: instance method of EventsCoreAPI
Returns: boolean - If signature matches return true else return false

Param Type Description
event * JSON payload delivered to the registered webhook URL
recipientClientId * Target recipient client id retrieved from the Adobe I/O Console integration
signatureOptions * map of all digital signature header values consisting fields as below digiSignature1 : Value of digital signature retrieved from the x-adobe-digital-signature1 header in each POST request to webhook digiSignature2 : Value of digital signature retrieved from the x-adobe-digital-signature2 header in each POST request to webhook publicKeyPath1 : Relative path of ioevents public key retrieved from the x-adobe-public-key1-path header in each POST request to webhook publicKeyPath2 : Relative path of ioevents public key retrieved from the x-adobe-public-key2-path header in each POST request to webhook

init(organizationId, apiKey, accessToken, [httpOptions]) ⇒ Promise.<EventsCoreAPI>

Returns a Promise that resolves with a new EventsCoreAPI object.

Kind: global function
Returns: Promise.<EventsCoreAPI> - returns object of the class EventsCoreAPI

Param Type Description
organizationId string The organization id from your integration
apiKey string The api key from your integration
accessToken string JWT Token for the integration with IO Management API scope
[httpOptions] EventsCoreAPIOptions Options to configure API calls

EventsCoreAPIOptions : object

Kind: global typedef
Properties

Name Type Description
[timeout] number Http request timeout in ms (optional)
[retries] number Number of retries in case of 5xx errors. Default 0 (optional)
[eventsBaseURL] string Base URL for Events Default https://api.adobe.io (optional)
[eventsIngressURL] string Ingress URL for Events. Default https://eventsingress.adobe.io (optional)

ProviderFilterOptions : object

Kind: global typedef
Properties

Name Type Description
[providerMetadataId] string Fetch by providerMetadataId for the consumer org
[instanceId] string For Self registered providers, instanceId is a must while fetching by providerMetadataId
[providerMetadataIds] Array.<string> Fetch all providers ( and all instances ) for the list of provider metadata ids

ProviderOptions : object

Kind: global typedef
Properties

Name Type Description
fetchEventMetadata boolean Option to fetch event metadata for each of the the providers in the list
filterBy ProviderFilterOptions Provider filtering options based on either (providerMetadataId and instanceId) or list of providerMetadataIds

ProviderInputModel : object

Kind: global typedef
Properties

Name Type Description
label string The label of this Events Provider
[description] string The description of this Events Provider
[docs_url] string The documentation url of this Events Provider

EventMetadataInputModel : object

Kind: global typedef
Properties

Name Type Description
label string The description of this Event Metadata
description string The label of this Event Metadata
event_code string The event_code of this Event Metadata. This event_code describes the type of event. Ideally it should be prefixed with a reverse-DNS name (dictating the organization which defines the semantics of this event type) It is equivalent to the CloudEvents' type. See https://github.com/cloudevents/spec/blob/master/spec.md#type
[sample_event_template] string An optional base64 encoded sample event template

EventsOfInterest : object

Kind: global typedef
Properties

Name Type Description
provider_id string The id of the provider of the events to be subscribed
event_code string The requested valid event code belonging to the provider

RegistrationCreateModel : object

Kind: global typedef
Properties

Name Type Description
client_id string Client id for which the registration is created
name string The name of the registration
description string The description of the registration
[webhook_url] string A valid webhook url where the events would be delivered for webhook or webhook_batch delivery_type
events_of_interest Array.<EventsOfInterest> The events for which the registration is to be subscribed to
delivery_type string Delivery type can either be webhook
[enabled] string Enable or disable the registration. Default true.

RegistrationUpdateModel : object

Kind: global typedef
Properties

Name Type Description
name string The name of the registration
description string The description of the registration
[webhook_url] string A valid webhook url where the events would be delivered for webhook or webhook_batch delivery_type
events_of_interest Array.<EventsOfInterest> The events for which the registration is to be subscribed to
delivery_type string Delivery type can either be webhook
[enabled] string Enable or disable the registration. Default true.

Page : object

Kind: global typedef
Properties

Name Type Description
[page] number page number to be fetched. Default 0 (optional)
[size] number size of each page. Default 10 (optional)

EventsJournalOptions : object

Kind: global typedef
Properties

Name Type Description
[latest] boolean Retrieve latest events (optional)
[since] string Position at which to start fetching the events from (optional)
[limit] number Maximum number of events to retrieve (optional)

EventsJournalPollingOptions : object

Kind: global typedef
Properties

Name Type Description
[interval] number Interval at which to poll the journal; If not provided, a default value will be used (optional)

Debug Logs

LOG_LEVEL=debug <your_call_here>

Prepend the LOG_LEVEL environment variable and debug value to the call that invokes your function, on the command line. This should output a lot of debug data for your SDK calls.

Contributing

Contributions are welcome! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.