Some basic docs to get started with

[wibblymat]

R: @kaycebasques @gauntface
CC: @petele

[gauntface]

Would it be worth changing this to just be steps to use rather than an explainer of the API?

I'd expect API docs to explain the API itself and the README be the rough steps to get this working.

1. install the library

   npm install ....
   

2. Send a payload to a subscription.

   // Subscription should be stored on your backend {endpoint: '.....', keys: {auth: '....', p256dh: '...'}}
   sendWebPush(data, subscription);
   

Question regarding API - was there a reason for not handling the authentication header inside the library rather than the developer having to manage it?

[wibblymat]

addAuthToken may be a bad name, then... it is the method you use to tell the library what your API key is for that service. You call it once in your application, not per message sent. So for GCM I'd do:

webpush.addAuthToken('.googleapis.com/gcm', '<string I copied from console.developers.google.com>');

subscriptions.forEach(sub => webpush.sendWebPush('whatever', subscription));

Does that make sense? The actual Authentication: key=BLAH header is added to the POST request by the library.

[petele]

Nit: I thought the plan for ES2015 usage was to use it in the libraries, but keep samples and docs in plain JS?

[gauntface]

never heard this being discussed but it's a good point - it probably should be.

[petele]

Added a few comments, if you gave this to me today and said go, it would take me too long to figure out how to use it. I want a quick start explanation to get me going immediately, then go from there.

[gauntface]

Ta for the explanation, still not entirely convinced by this API though.

1.) If it's only used by GCM, then should it just be of addGCMAuthToken('');
2.) If it is for other push providers or will be in the future - it presumably would just be a server key or something to that affect and would be shared across all push providers meaning you could have

webpush.addGCMAuthToken('');
webpush.addAuthToken('');

Essentially - I just really dislike the pattern requirement - feels to error prone and boilerplate.

SIDE NOTE: This should probably be moved to an issue and doesn't block these this docs PR.

[gauntface]

+1 Peters comments.

I think keep this on the bare minimum titled getting started to just install and use the library for Chrome and Firefox.

We can either than add further comments in API docs OR seperate sections. For now I'd go minimal and start asking people for feedback and iterate on it.

[gauntface]

Moved auth token comments to: #6 would appreciate any feedback.

[wibblymat]

@gauntface @petele I simplified the docs, removing the API reference.

I also simplified the auth token business - auth token is now a parameter of sendWebPush and we push the process onto the developer. This came up in the code review for the Go version, too, and in the end it seemed like it was actually easier for developers to grok what was going on if they were left in control.

[gauntface]

Is this the name we are actually published on? Does it make sense to make it slightly more generic if we can support encrypted push and just tickles?

[wibblymat]

I wanted web-push but Mozilla got there first :)

Will open an issue.

[gauntface]

LGTM

Commented on the naming of the module, but that can be moved to an issue.