* lib: remove specversion from the required attributes in receiver.accept()
The `HTTPReceiver` class' `accept()` method should not have a typescript
type designation of `{ specversion: string }` for the `body` parameter
because the event could (and often is) in binary form, which means that
the `specversion` property won't be there.
This commit changes the method signature to:
`accept(headers: {}, body: {}) : CloudEvent`
Signed-off-by: Lance Ball <lball@redhat.com>
This commit modifies the existing TypeScript files with improved
(read: functional) typings for function parameters. This became an
issue when trying to use the module in an existing TypeScript module.
Tests for the TypeScript files have been moved to a new test folder
specifically for testing TypeScript usage via ts-node.
Signed-off-by: Lance Ball <lball@redhat.com>
This extracts all of the attributes from a `CloudEventVX` that
are not generated by the constructor (id and specversion) into their
own `CloudEventVXAttributes` interface which the `CloudEventVX`
interface extends. This allows TS devs to optionally provide `id`
and `specversion` with proper autocompletion.
Additionally, I have added a union type, `CE` in `cloudevent.ts` which
represents any of `CloudEventV1`, `CloudEventv03`, `CloudEventV1Attributes`
and `CloudEventV03Attributes` interfaces.
Finally, this commit changes all of the user facing API to be `.ts` instead
of `.js` files.
The existing documentation in `./docs` was removed. It should be replaced with generated
HTML from tsdocs, pending some other method of publishing API documentation. That will
come as a separate, docs-only PR.
Fixes: https://github.com/cloudevents/skd-javascript/issues/188
Signed-off-by: Lance Ball <lball@redhat.com>
GitHub will not set secrets in the environment when a pull request is submitted
from a forked repository. This commit modifies the CI workflow to only send
the report when the API token has been set. It also consolidates the two
workflows into a single one which shares coverage data between jobs.
Fixes: https://github.com/cloudevents/sdk-javascript/issues/190
Signed-off-by: Lance Ball <lball@redhat.com>
This commit makes a substantial change to the API, changing the CloudEvent class
to accept properties as an object in the constructor. For example:
```js
const CloudEvent = require('cloudevents-sdk');
// all event properties except extensions may be set in the constructor
const event = new CloudEvent({
source: 'http://my.event.source',
type: 'test-event-type'
});
// get and set all properties standard property notation
console.log(event.time); // the event timestamp
event.subject = 'my event subject';
```
Signed-off-by: Lance Ball <lball@redhat.com>
This commit turns the headerByGetter Object into a Map to reduces some
code duplication an hopefully improve readability a little.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit introduces TypeScript checks and generates type declarations
for the existing JavaScript codebase using `tsc` prior to running the linter task.
Ref: https://github.com/cloudevents/sdk-javascript/issues/9
Signed-off-by: Lance Ball <lball@redhat.com>
This is a breaking change.
This commit makes a number of changes to the HTTP bindings code in an attempt
to simplify its usage and implementation. From a very high level, this inverts
the existing dependencies.
As an example, consider `lib/bindings/http/receiver_structured_1.js`.
https://github.com/cloudevents/sdk-javascript/blob/v1.0.0/lib/bindings/http/receiver_structured_0_3.js
This class instantiates `lib/bindings/http/receiver_structured.js` and delegates
its function invokations to it. This had the effect of requiring a user to know what
event versions they would be receiving. And for me personally was a little confusing
as a maintainer.
The change introduced here reverses that logic, so that the version agnostic receiver
is what the user instantiates. It instantiates the approrpiate version of a specific
receiever and delegates to it - reversing the dependencies.
I've also moved all of the top level directories related to HTTP versions into
`lib/bindings/http/v1` and `lib/bindings/http/v03` and generally done some rearranging
to make the repository structure cleaner and more organized.
Signed-off-by: Lance Ball <lball@redhat.com>
This commit pulls the constants up from the lib/bindings/http/constants.js
and exports them in the top level index.js. There are some elements of the API
where we expect users to provide constant values, and this makes it easier for
them to be sure the values they provide are what is expected.
I've also added two new constants: `BINARY` and `STRUCTURED`.
Signed-off-by: Lance Ball <lball@redhat.com>
This commit removes the 'result' variable form the utility function
asData. The motivation is to improve readability.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit removes the version variable from getVersion and updates the
code to use return statements to be consistent with other functions in
this file, like getMode and accept.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
* feat!: expose a version agnostic event emitter
This is a breaking change.
This commit exposes an HTTP based event emitter that simplifes the API.
To use it, simply import the SDK and start emitting. The default spec
version is 1.0, but you can use 0.3 by supplying that to the constructor.
By default, CloudEvents are emitted in binary mode, but this can be changed
by providing the "structured" parameter to the `send()` function.
This commit also eliminates the version specific emitters and receivers
from the `v1` and `v03` exports, and eliminates the explicit usage of
versioned emitters from `lib/bindings/http`.
Finally, the CE headers can be retrieved from the emitter for a given
event by passing the event to the `headers()` function.
Fixes: https://github.com/cloudevents/sdk-javascript/issues/124
Fixes: https://github.com/cloudevents/sdk-javascript/issues/149
Signed-off-by: Lance Ball <lball@redhat.com>
This change adds a `ValidationError` type that extends `TypeError`. Any time a `CloudEvent` cannot be received and created with the given input, this error will be thrown. Tests have all
been updated to check for the error type.
Signed-off-by: Lance Ball <lball@redhat.com>
This commit changes the setterByAttribute to be a map and tries to
reduce some code duplication and improve readability.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
After updating and running npm install the package-lock.json file is
updated. I can see that packate-lock.json was included in
Commit b283583c0c ("docs: add JSDocs for
top level API objects") but perhaps there were changes to package.json
that were made after and went unnoticed.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit add JSDoc documentation to the CloudEvent and HTTPReceiver
objects exposed by the API when using the top level imports, specifically
`CloudEvent` and `HTTPReceiver`.
This adds a `generate-docs` npm script to generate site and API documentation
for GitHub pages in `./docs`.
Signed-off-by: Lance Ball <lball@redhat.com>
Currently, the mode variable in getMode is set to 'unknown' but this
will never get returned as the else clause will throw a TypeError if the
detected mode (from the passed-in headers) is not structured or binary.
This commit suggests simplifying the getMode function and removes the
mode variable.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit adds the '.js' suffix to the require of receiver_binary_0_3
to be consistent with the other requires statments in this file.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit removes the require of uuid from this test and uses a
hardcoded value for the 'id' constant instead.
The motivation for this is that the value for 'id' does not need to be
generated for each test run, and fewer requires helps readabilitly I
find.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit removes two unnecessary else clauses in unmarshaller.js, and
also extracts the throwing of TypeError of invalid content types into a
separate function to avoid some code duplication.
Signed-off-by: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit adds instructions and details to contributors guide and provides detailed guidance for pull requests and maintainers in separate documents.
Signed-off-by: Lance Ball <lball@redhat.com>
This commit changes the event mode detection in `HTTPReceiver` so that it will
throw a TypeError if the event mode can't be detected per the spec.
Signed-off-by: Lance Ball <lball@redhat.com>
This commit modifies the README to show new API usage for the
`HTTPReceiver` and `CloudEvent` classes, and updates the examples
to use this as well.
Overall structure and content has been modified to look more like
the sdk-go README.
Fixes: https://github.com/cloudevents/sdk-javascript/issues/128
Signed-off-by: Lance Ball <lball@redhat.com>
* fix: ensure binary events can handle no content-type header
The fix provided in https://github.com/cloudevents/sdk-javascript/pull/118
only included tests for `receiver.check()`, and the change in that
case was to add the `application/json` content type to the cleansed
headers if to type was specified.
However, `receiver.parse()` did not receive the benefit of this change. It
calls `this.check()` but then sanitizes the original headers again, and the
missing content-type was not re-inserted into the newly sanitized headers.
This commit, modifies the code so that `receiver.check()` does not insert
the content-type, but does allow the validation check to pass if no
content-type header exists. When `receiver.parse()` is called, and the
headers are sanitized again - and this time used to look up parser implementation,
the default `application/json` content-is applied if no content-type header
exists.
I've also removed a redundant call to `receiver.check()` in receiver_binary_1.js
and simplified the usage of `Constants` in the test.
Signed-off-by: Lance Ball <lball@redhat.com>
* chore: clean up header sniffing
Signed-off-by: Lance Ball <lball@redhat.com>
This commit removes the unnecessary use of Promises in the 0.3 unmarshaller.
There was actually no asynchronous activity happening in that function, so
there was no need to deal with Promises, and as a result testing was made
much more difficult.
Fixes: https://github.com/cloudevents/sdk-javascript/pull/95
Signed-off-by: Lance Ball <lball@redhat.com>
* fix: make application/json the default content type in binary mode (#118)
The Knative Kafka event source does not include a `Content-Type` header when
sending binary events. The CE HTTP binding specification doesn't address how
a receiver should handle this situation.
This commit makes `application/json` the default.
Fixes: https://github.com/cloudevents/sdk-javascript/issues/117
Ref: https://github.com/cloudevents/spec/issues/614
Signed-off-by: Lance Ball <lball@redhat.com>
Signed-off-by: Grant Timmerman <timmerman+devrel@google.com>
* refactor: remove ext folder
Signed-off-by: Grant Timmerman <timmerman+devrel@google.com>
* Revert "fix: make application/json the default content type in binary mode (#118)"
This reverts commit 9ccfaf25ba.
Signed-off-by: Grant Timmerman <timmerman+devrel@google.com>
Co-authored-by: Lance Ball <lball@redhat.com>
Event receivers in the wild may not always know what version or mode an
incoming event is. Instead of requiring developers to inspect the headers
themselves, the SDK should provide an HTTP receiver that is capable of
figuring out what the version and mode (structured/binary) of an incoming
event is and handle it appropriately.
In determining the best way to expose this, I chose to modify the API a
little bit. Now, instead of `const CloudEvent = require('cloudevents-sdk');`
users need to destructure it.
```js
const { HTTPReceiver, CloudEvent } = require('cloudevents-sdk');
```
This change should not be backported to 1.x.
Fixes: https://github.com/cloudevents/sdk-javascript/issues/93
Signed-off-by: Lance Ball <lball@redhat.com>
Grant Timmerman
Lucas Holmquist
Lance Ball
Doug Davis
Ali Ok
Daniel Bevenius
Helio Frota