API cleanup

CHANGELOG.md

@@ -1,19 +1,22 @@
-## 1.2.0  October 26, 2012
+## 2.0.0  November 1, 2012
 
 New API for updating structure fields:
 
   passbook.headerFields.add("time", "The Time", "10:00AM");
-  passbook.backFields.add("url", "Web site", "http://example.com");
+  passbook.backFields.add({ key: "url", label: "Web site", value: "http://example.com" });
   console.log(passbook.backFields.get("url"));
   passbook.backFields.remove("url");
   console.log(passbook.backFields.all());
 
-passbook.pipe is now passbook.writeToOutputStream, which better reflects what it
-does.
+The `pipe` method no longer accepts a callback, instead, register listener on
+the `end` and `error` events.
 
-Added passbook.render to render a Passbook to an HTTP response.
+For HTTP servers, you can use the `render` method.
 
-Should send complete bufferred resources first.
+New optimization to send completes resources first (useful when downloading
+images from URLs).
+
+Renamed `createPassbook` to `createPass`.
 
 
 ## 1.1.1  October 24, 2012

README.md

@@ -21,92 +21,142 @@ This is the same directory into which you placet the `.p12` files.
 # Start with a template
 
 Start with a template.  A template has all the common data fields that will be
-shared between your passbook, and also defines the keys to use for signing it.
+shared between your passes, and also defines the keys to use for signing it.
 
 ```
 var createTemplate = require("passbook");
 
 var template = createTemplate("coupon", {
   passTypeIdentifier: "pass.com.example.passbook",
   teamIdentifier:     "MXL",
-  "backgroundColor":   "rgb(255,255,255)"
+  backgroundColor:   "rgb(255,255,255)"
 });
-template.keys("/etc/passbook/keys", "secret");
 ```
 
-The first argument is the Passbook style (`coupon`, `eventTicket`, etc), and the
-second optional argument has any fields you want to set on th template.
+The first argument is the pass style (`coupon`, `eventTicket`, etc), and the
+second optional argument has any fields you want to set on the template.
 
 You can access template fields directly, or from chained accessor methods, e.g:
 
 ```
 template.fields.passTypeIdentifier = "pass.com.example.passbook";
+
 console.log(template.passTypeIdentifier());
+
 template.teamIdentifier("MXL").
   passTypeIdentifier("pass.com.example.passbook")
 ```
 
-The template fields are `passTypeIdentifier`, `teamIdentifier`,
-`backgroundColor`, `foregroundColor`, `labelColor`, `logoText`,
-`organizationName`, `suppressStripShine` and `webServiceURL`.
+The following template fields are required:
+`passTypeIdentifier`  - The Passbook Type ID, begins with "pass."
+`teamIdentifier`      - May contain an I
+
+Optional fields that you can set on the template (or pass): `backgroundColor`,
+`foregroundColor`, `labelColor`, `logoText`, `organizationName`,
+`suppressStripShine` and `webServiceURL`.
 
-The first two are required: `passTypeIdentifier` is the Passbook Type ID, begins
-with "pass." and has to be registered with Apple.  The `teamIdentifier` may
-contain an I.
+In addition, you need to tell the template where to find the key files and where
+to load images from:
 
-All other fields can be set on either template or passbook.
+```
+template.keys("/etc/passbook/keys", "secret");
+template.loadImagesFrom("images");
+```
 
+The last part is optional, but if you have images that are common to all passes,
+you may want to specify them once in the template.
 
-# Create your passbook
 
-To create a new passbook from a template:
+# Create your pass
+
+To create a new pass from a template:
 
 ```
-var passbook = template.createPassbook({
+var pass = template.createPass({
   serialNumber:  "123456",
   description:   "20% off"
 });
 ```
 
-Just like template, you can access Passbook fields directly, or from chained
+Just like template, you can access pass fields directly, or from chained
 accessor methods, e.g:
 
 ```
-passbook.fields.serialNumber = "12345";
-console.log(passbook.serialNumber());
-passbook.serialNumber("12345").
+pass.fields.serialNumber = "12345";
+console.log(pass.serialNumber());
+pass.serialNumber("12345").
   description("20% off");
 ```
 
-You can also access structure fields directly, or from chained accessor methods.
-The following three are equivalent:
+In the JSON specification, structure fields (primary fields, secondary fields,
+etc) are represented as arrays, but items must have distinct key properties.  Le
+sigh.
+
+To make it easier, you can use methods like `add`, `get` and `remove` that
+will do the logical thing.  For example, to add a primary field:
 
 ```
-passbook.fields.coupon.headerFields = header;
-passbook.structure.headerFields = header;
-passbook.headerFields(header);
+pass.primaryFields.add("date", "Date", "Nov 1");
+pass.primaryFields.add({ key: "time", label: "Time", value: "10:00AM");
+```
+
+You can also call `add` with an array of triplets or array of objects.
+
+To get one or all fields:
+
 ```
+var dateField = pass.primaryFields.get("date");
+var allFields = pass.primaryFields.all();
+```
+
+To remove one or all fields:
+
+```
+pass.primaryFields.remove("date");
+pass.primaryFields.clear();
+```
+
+Adding images to a pass is the same as adding images to a template:
+
+```
+pass.images.icon = iconFilename;
+pass.icon(iconFilename);
+pass.loadImagesFrom("images");
+```
+
+You can add the image itself (a `Buffer`), or provide the name of a file or an
+HTTP/S URL for retrieving the image.  You can also provide a function that will
+be called when it's time to load the image, and should pass an error, or `null`
+and a buffer to its callback. 
+
+
+# Generate the file
 
-Same drill when it comes to adding images to your Passbook:
+To generate a file:
 
 ```
-passbook.images.icon = iconFilename;
-passbook.icon(iconFilename);
+var file = File.createWriteStream("mypass.pkpass");
+passbook.on("error", function(error) {
+  console.error(error);
+  process.exit(1);
+})
+passbook.pipe(output);
 ```
 
-You can add the image itself (`Buffer`), the name of a file containing the image
-(`String`), or a function that will be called to load the image, and should pass
-an error, or `null` and a `Buffer` to its callback.
+Your pass will emit the `error` event if it fails to generate a valid Passbook
+file, and emit the `end` event when it successfuly completed generating the
+file.
 
-Finally, to generate a Passbook file:
+You can pipe to any writeable stream.  When working with HTTP, the `render`
+method will set the content type, pipe to the HTTP response, and make use of a
+callback (if supplied).
 
 ```
-passbook.generate(function(error, buffer) {
-  if (error) {
-    console.log(error);
-  } else {
-    File.writeFile("passbook.pkpass", buffer);
-  }
+server.get("/mypass", function(request, response) {
+  passbook.render(response, function(error) {
+    if (error)
+      console.error(error);
+  });
 });
 ```
 

lib/images.js

@@ -17,14 +17,14 @@ function applyImageMethods(constructor) {
   // Call with an argument to set the image and return self, call with no
   // argument to get image value.
   //
-  //   passbook.icon(function(callback) { ... };
-  //   console.log(passbook.icon());
+  //   pass.icon(function(callback) { ... };
+  //   console.log(pass.icon());
   //
   // The 2x suffix is used for high resolution version (file name uses @2x
   // suffix).
   //
-  //   passbook.icon2x("[email protected]");
-  //   console.log(passbook.icon2x());
+  //   pass.icon2x("[email protected]");
+  //   console.log(pass.icon2x());
   IMAGES.forEach(function(key) {
     prototype[key] = function(value) {
       if (arguments.length === 0) {

lib/index.js

@@ -1,16 +1,15 @@
 // Exports function for creating a new template, from which you can create new
-// passbooks.
+// passes.
 
 var Template = require("./template");
 
 
 // Create a new template.
 //
-// style  - Passbook style (coupon, eventTicket, etc)
-// fields - Passbook fields (passTypeIdentifier, teamIdentifier, etc) 
+// style  - Pass style (coupon, eventTicket, etc)
+// fields - Pass fields (passTypeIdentifier, teamIdentifier, etc) 
 function createTemplate(style, fields) {
   return new Template(style, fields);
 }
 
 module.exports = createTemplate;
-