Updated API and README documents

API.md

@@ -34,16 +34,19 @@ ___
 	* [Localizing Passes](#localizing_passes)
 		* [.localize()](#method_localize)
 	* Setting barcode
+		* [.barcodes()](#method_barcodes)
 		* [.barcode()](#method_barcode)
-			* [.backward()](#method_bBackward)
-			* [.autocomplete()](#method_bAutocomplete)
 	* Setting expiration / voiding the pass
 		* [.expiration()](#method_expiration)
 		* [.void()](#method_void)
 	* Setting relevance
-		* [.relevance()](#method_relevance)
+		* [.beacons()](#method_beacons)
+		* [.locations()](#method_locations)
+		* [.relevantDate()][#method_revdate]
 	* Setting NFC
 		* [.nfc()](#method_nfc)
+	* Getting the current information
+		* [.props](#getter_props)
 	* [Setting Pass Structure Keys (primaryFields, secondaryFields, ...)](#prop_fields)
 		* [TransitType](#prop_transitType)
 	* Generating the compiled pass.
@@ -56,20 +59,20 @@ ___
 
 #### constructor()
 
-```javascript
+```typescript
-var pass = new Pass(options);
+const pass = await createPass({ ... });
 ```
 
 **Returns**:
 
-`Object<Pass>`
+`Promise<Pass>`
 
 **Arguments**:
 
 | Key | Type | Description | Optional | Default Value |
 |-----|------|---------------|:-------------:|:-----------:|
 | options | Object | The options to create the pass | false | -
-| options.model | String/Path | The model path to be used to generate a new model. | false | -
+| options.model | String/Path/Buffer Object | The model path or a Buffer Object with path as key and Buffer as content | false | -
 | options.certificates | Object | The certificate object containing the paths to certs files. | false | -
 | options.certificates.wwdr | String/Path | The path to Apple WWDR certificate or its content. | false | -
 | options.certificates.signerCert | String/Path | The path to Developer certificate file or its content. | false | -
@@ -77,7 +80,6 @@ var pass = new Pass(options);
 | options.certificates.signerKey.keyFile | String/Path | The path to developer certificate key or its content. | false | -
 | options.certificates.signerKey.passphrase | String \| Number | The passphrase to use to unlock the key. | false | -
 | options.overrides | Object | Dictionary containing all the keys you can override in the pass.json file and does not have a method to get overridden. | true | { }
-| options.shouldOverwrite | Boolean | Setting this property to false, will make properties in `overrides` and fields to be pushed along with the ones added through methods to the existing ones in pass.json. | true | true
 
 <br><br>
 <a name="localizing_passes"></a>
@@ -90,6 +92,7 @@ Following Apple Developer Documentation, localization (L10N) is done by creating
 
 In this library, localization can be done in three ways: **media-only** (images), **translations-only** or both.
 The only differences stands in the way the only method below is used and how the model is designed.
+If this method is used for translations and the model already contains a `pass.strings` for the specified language, the translations will be appended to that file.
 
 > If you are designing your pass for a language only, you can directly replace the placeholders in `pass.json` with translation.
 
@@ -98,8 +101,8 @@ The only differences stands in the way the only method below is used and how the
 
 #### .localize()
 
-```javascript
+```typescript
-pass.localize(lang, options);
+pass.localize(lang: string, options = {});
 ```
 
 **Returns**:
@@ -119,7 +122,7 @@ In the other two cases, you'll need to specify also the second argument (the tra
 | Key | Type | Description | Optional | Default Value |
 |-----|------|-------------|----------|:-------------:|
 | lang | String | The ISO-3166-1 language code | false | -
-| options | Object | Translations in format PLACEHOLDER : TRANSLATED-VALUE. | true | undefined \| { }
+| options | Object | Translations in format `{ <PLACEHOLDER>: "TRANSLATED-VALUE"}`. | true | undefined \| { }
 
 **Example**:
 
@@ -142,72 +145,66 @@ ___
 **Setting barcodes**:
 ___
 
+<a name="method_barcodes"></a>
+
+#### .barcodes()
+
+```typescript
+pass.barcodes(first: string | schema.Barcode, ...data: schema.Barcodes[]) : this;
+```
+
+**Returns**:
+
+`Object<Pass> (this)`
+
+**Description**:
+
+Setting barcodes can happen in two ways: `controlled` and `uncontrolled` (autogenerated), which mean how many [barcode structures](https://apple.co/2myAbst) you will have in your pass.
+
+Passing a `string` to the method, will lead to an `uncontrolled` way: starting from the message (content), all the structures will be generated. Any further parameter will be ignored.
+
+Passing *N* barcode structures (see below), will only validate them and push only the valid ones.
+
+This method will not take take of setting retro-compatibility, of which responsability is assigned to `.barcode()`.
+
+**Arguments**:
+
+|  Key  | Type | Description | Optional |
+|-------|------|-------------|----------|
+| first | `String` \| `schema.Barcode` | first value of barcodes | false
+| ...data | `schema.Barcode[]` | the other barcode values | true
+
+**Examples**:
+
+```typescript
+pass.barcodes("11424771526");
+
+// or
+
+pass.barcodes({
+	message: "11424771526",
+	format: "PKBarcodeFormatCode128"
+	altText: "11424771526"
+}, {
+	message: "11424771526",
+	format: "PKBarcodeFormatQR"
+	altText: "11424771526"
+}, {
+	message: "11424771526",
+	format: "PKBarcodeFormatPDF417"
+	altText: "11424771526"
+});
+```
+
+**See**: [PassKit Package Format Reference # Barcode Dictionary](https://apple.co/2myAbst)
+<br>
+<br>
 <a name="method_barcode"></a>
 
 #### .barcode()
 
 ```javascript
-pass.barcode(data);
+pass.barcode(data: string);
-```
-
-**Returns**:
-
-`Improved Object<Pass> (this with some "private" methods available to be called under aliases, as below)`
-
-**Description**:
-
-Each object in `data` will be filtered against a schema ([Apple reference](https://apple.co/2myAbst)) validation and used if correctly formed.
-
-If the argument is an Object, it will be treated as one-element Array.
-
-If the argument is a String or an Object with `format` parameter missing, but `message` available, the structure will be **autogenerated** complete of all the fallbacks (4 dictionaries).
-
-To support versions prior to iOS 9, `barcode` key is automatically supported as the first valid value of the provided (or generated) barcode. To change the key, see below.
-
-**Arguments**:
-
-| Key | Type | Description | Optional | Default Value |
-|-----|------|-------------|----------|:-------------:|
-| data | String \| Array\<Object> \| Object | Data to be used in the barcode | false | -
-
-**Examples**:
-
-```javascript
-	pass.barcode("11424771526");
-
-	// or
-
-	pass.barcode({
-		message: "11424771526",
-		format: "PKBarcodeFormatCode128"
-		altText: "11424771526"
-	});
-
-	// or
-
-	pass.barcode([{
-		message: "11424771526",
-		format: "PKBarcodeFormatCode128"
-		altText: "11424771526"
-	}, {
-		message: "11424771526",
-		format: "PKBarcodeFormatQR"
-		altText: "11424771526"
-	}, {
-		message: "11424771526",
-		format: "PKBarcodeFormatPDF417"
-		altText: "11424771526"
-	}]);
-```
-
-**See**: [PassKit Package Format Reference # Barcode Dictionary](https://apple.co/2myAbst)
-<br>
-<a name="method_bBackward"></a>
-
-#### .barcode().backward()
-
-```javascript
-pass.barcode(data).backward(format);
 ```
 
 **Returns**:
@@ -217,44 +214,30 @@ pass.barcode(data).backward(format);
 **Description**:
 
 It will let you choose the format to be used in barcode property as backward compatibility.
-Also it will work only if `data` is provided to `barcode()` method and will fail if the selected format is not found among barcodes dictionaries array.
+Also it will work only if `barcodes()` method has already been called or if the current properties already have at least one barcode structure in it and if it matches with the specified one.
+
+`PKBarcodeFormatCode128` is not supported in barcode. Therefore any attempt to set it, will fail.
 
 **Arguments**:
 
 | Key | Type | Description | Optional | Default Value |
 |-----|------|-------------|----------|:-------------:|
-| format | String | Format to be used. Must be one of these types: *PKBarcodeFormatQR*, *PKBarcodeFormatPDF417*, *PKBarcodeFormatAztec* | false | -
+| format | String | Format to be used. Must be one of these types: `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec` | false | -
 
 **Example**:
 
 ```javascript
-// Based on the previous example
+// Based on the previous (barcodes) example
 pass
-	.barcode(...)
+	.barcodes(...)
-	.backward("PKBarcodeFormatQR");
+	.barcode("PKBarcodeFormatQR");
 
 // This won't set the property since not found.
 pass
-	.barcode(...)
+	.barcodes(...)
-	.backward("PKBarcodeFormatAztec");
+	.barcode("PKBarcodeFormatAztec");
 ```
 
-<br>
-<a name="method_bAutocomplete"></a>
-
-#### .barcode().autocomplete()
-
-```javascript
-pass.barcode(data).autocomplete();
-```
-
-**Returns**:
-
-`Improved Object<Pass> ("this" with backward() support and length prop. reporting how many structs have been added).`
-
-**Description**:
-
-It will generate all the barcodes fallback starting from the first dictionary in `barcodes`.
 
 <br><br>
 ___
@@ -266,8 +249,8 @@ ___
 
 #### .expiration()
 
-```javascript
+```typescript
-pass.expiration(date [, format]);
+pass.expiration(date: Date) : this;
 ```
 
 **Returns**:
@@ -276,22 +259,18 @@ pass.expiration(date [, format]);
 
 **Description**:
 
-It sets the date of expiration to the passed argument. The date will be automatically parsed in order in the following formats:
+It sets the date of expiration to the passed argument.
-
-* **MM-DD-YYYY hh:mm:ss**,
-* **DD-MM-YYYY hh:mm:ss**.
-
-Otherwise you can specify a personal format to use.
-
-Seconds are not optionals.
 If the parsing fails, the error will be emitted only in debug mode and the property won't be set.
+Passing `null` as the parameter, will remove the value.
 
 **Arguments**:
 
-| Key | Type | Description | Optional | Default Value |
+| Key | Type | Description | Optional |
-|-----|------|-------------|----------|:-------------:|
+|-----|------|-------------|----------|
-| date | String/date | The date on which the pass will expire | false | -
+| date | String/date | The date on which the pass will expire | false
-| format | String | A custom format to be used to parse the date | true | undefined
+
+<br>
+<hr>
 
 <a name="method_void"></a>
 
@@ -307,7 +286,7 @@ pass.void();
 
 **Description**:
 
-It sets directly the pass as voided (void: true).
+It sets directly the pass as voided.
 
 <br><br>
 ___
@@ -315,53 +294,107 @@ ___
 **Setting relevance**:
 ___
 
-<a name="method_relevance"></a>
+<a name="method_beacons"></a>
 
-#### .relevance()
+#### .beacons()
 
-```javascript
+```typescript
-pass.relevance(key, value [, relevanceDateFormat]);
+pass.beacons(...data: schema.Beacons[]): this;
 ```
 
 **Returns**:
 
-`Improved Object<Pass> (this with length property)`
+`Object<Pass> (this)`
 
 **Description**:
 
-It sets the relevance key in the pass among four: **beacons**, **locations**, **relevantDate** and **maxDistance**.
+Sets the beacons information in the passes.
-See [Apple Documentation dedicated page](https://apple.co/2QiE9Ds) for more.
+If other beacons structures are available in the structure, they will be overwritten.
-
+Passing `null` as parameter, will remove the content.
-For the first two keys, the argument 'value' (which will be of type **Array\<Object>**) will be checked and filtered against dedicated schema.
-
-For *relevantDate*, the date is parsed in the same formats of [#expiration()](#method_expiration). For *maxDistance*, the value is simply converted as Number and pushed only with successful conversion.
-
 
 **Arguments**:
 
 | Key | Type | Description | Optional | Default Value |
 |-----|------|-------------|----------|:-------------:|
-| key | String | The relevance key to be set, among **beacons**, **locations**, **relevantDate** and **maxDistance** | false | -
+| ...data | [schema.Beacons[]](https://apple.co/2XPDoYX) \| `null` | The beacons structures | false | -
-| value | String \| Number \| Array\<Object> | Type depends on the key. Please refer to the description above for more details | false | -
-| relevanceDateFormat | String | Custom date format. Will be only used when using `relevanceDate` key | true | undefined
 
 **Example**:
 
-```javascript
+```typescript
-pass.relevance("location", [{
+pass.beacons({
-	longitude: "73.2943532945212",
+	"major": 55,
-	latitude: "-42.3088613015625",
+	"minor": 0,
-]);
+	"proximityUUID": "59da0f96-3fb5-43aa-9028-2bc796c3d0c5"
-
+}, {
-pass.relevance("maxDistance", 150);
+	"major": 65,
-
+	"minor": 46,
-// DD-MM-YYYY -> April, 10th 2021
+	"proximityUUID": "fdcbbf48-a4ae-4ffb-9200-f8a373c5c18e",
-pass.relevance("relevantDate", "10/04/2021", "DD-MM-YYYY");
+});
-
-// MM-DD-YYYY -> October, 4th 2021
-pass.relevance("relevantDate", "10/04/2021");
 ```
 
+<br>
+<hr>
+
+<a name="method_locations"></a>
+
+#### .locations()
+
+```typescript
+pass.locations(...data: schema.Locations[]): this;
+```
+
+**Returns**:
+
+`Object<Pass> (this)`
+
+**Description**:
+
+Sets the location-relevance information in the passes.
+If other location structures are available in the structure, they will be overwritten.
+Passing `null` as parameter, will remove its content;
+
+**Arguments**:
+
+| Key | Type | Description | Optional | Default Value |
+|-----|------|-------------|----------|:-------------:|
+| ...data | [schema.Locations[]](https://apple.co/2LE00VZ) \| `null` | The location structures | false | -
+
+**Example**:
+
+```typescript
+pass.locations({
+	"latitude": 66.45725212,
+	"longitude": 33.010004420
+}, {
+	"longitude": 4.42634523,
+	"latitude": 5.344233323352
+});
+```
+<br>
+<hr>
+
+<a name="method_relevantDate"></a>
+
+#### .relevantDate()
+
+```typescript
+pass.relevantDate(date: Date): this;
+```
+
+**Returns**:
+
+`Object<Pass> (this)`
+
+**Description**:
+
+Sets the relevant date for the current pass. Passing `null` to the parameter, will remove its content.
+
+**Arguments**:
+
+| Key | Type | Description | Optional | Default Value |
+|-----|------|-------------|----------|:-------------:|
+| date | Date \| `null` | The relevant date | false | -
+
 <br><br>
 ___
 
@@ -372,8 +405,8 @@ ___
 
 #### .nfc()
 
-```javascript
+```typescript
-pass.nfc([data, ...])
+pass.nfc(data: schema.NFC): this
 ```
 
 **Returns**:
@@ -382,23 +415,54 @@ pass.nfc([data, ...])
 
 **Description**:
 
-It sets the property for nfc dictionary.
+It sets NFC info for the current pass. Passing `null` as parameter, will remove its value.
-An Object as argument will be treated as one-element array.
 
 >*Notice*: **I had the possibility to test in no way this pass feature and, therefore, the implementation. If you need it and this won't work, feel free to contact me and we will investigate together 😄**
 
 **Arguments**:
 
-| Key | Type | Description | Optional | Default Value |
+| Key | Type | Description | Optional |
-|-----|------|-------------|----------|:-------------:|
+|-----|------|-------------|----------|
-| data | Array\<Object> \| Object | The data regarding to be used for nfc | false | -
+| data | [schema.NFC](https://apple.co/2XrXwMr) \| `null` | NFC structure | false
 
 **See**: [PassKit Package Format Reference # NFC](https://apple.co/2wTxiaC)
-<br><br>
-___
 
-**Getting remote resources**:
+<br><br>
-___
+<hr>
+
+<a name="getter_props"></a>
+
+#### .props()
+
+```typescript
+pass.props;
+```
+
+**Returns**:
+
+An object containing all the current props;
+
+**Description**:
+
+This is a getter: a way to access to the current props before generating a pass. In here are available the props set both from pass.json reading and this package methods usage, along with the valid overrides passed to `createPass`. The keys are the same used in pass.json.
+
+It does not contain fields content (`primaryFields`, `secondaryFields`...) and `transitType`, which are still accessible through their own props.
+
+**Example**:
+
+```typescript
+const currentLocations = pass.props["locations"];
+pass.locations({
+	"latitude": 66.45725212,
+	"longitude": 33.010004420
+}, {
+	"longitude": 4.42634523,
+	"latitude": 5.344233323352
+},
+...currentLocations);
+```
+
+<br><br>
 
 <a name="prop_fields"></a>
 ___

README.md

@@ -14,11 +14,12 @@
 
 ### Architecture
 
-This package was created with a specific architecture in mind: **application** and **model**, to split as much as possible static objects (such as logo, background, icon, etc.) from dynamic ones (translations, barcodes, serialNumber, ...).
+This package was created with a specific architecture in mind: **application** and **model** (as preprocessed entity), to split as much as possible static objects (such as logo, background, icon, etc.) from dynamic ones (translations, barcodes, serialNumber, ...).
 
-Actually, pass creation and population doesn't fully happen within the application in runtime. Pass template is a folder in, for example, _your application directory_ (but nothing will stop you from putting it outside), that will contain all the objects needed (static medias) and structure to make a pass work.
+Pass creation and population doesn't fully happen in runtime. Pass template (model) can be one of a set of buffers or a folder, that will contain all the objects needed (static medias) and structure to make a pass work.
 
-Pass template will be read and pushed as is in the resulting .zip file, while dynamic objects will be patched against `pass.json` or generated in runtime (`manifest.json`, `signature` and translation files).
+Both Pass template will be read and pushed as they are in the resulting .zip file, while dynamic objects will be patched against `pass.json` or generated in runtime (`manifest.json`, `signature` and translation files).
+All the static medias from both sources, will be read and pushed as they are in the resulting .zip file; dynamic object will be patched against `pass.json`, generated on runtime (`manifest.json`, `signature`) or merged if already existing (translation files).
 
 This package comes with an [API documentation](./API.md), that makes available a series of methods to customize passes.
 
@@ -35,14 +36,18 @@ ___
 
 ##### Model
 
-The first thing you'll have to do, is to start creating a model. A model is a folder in your project directory, with inside the basic pass infos, like the thumbnails, the icon, and the background and **pass.json** containing all the static infos about the pass, like Team identifier, Pass type identifier, colors, etc.
+The first thing you'll have to do, is to start creating a model. A model will contain all the basic pass infos, like the thumbnails, the icon, and the background and **pass.json** containing all the static infos about the pass, like Team identifier, Pass type identifier, colors, etc.
+
+If starting from scratch, the preferred solution is to use the folder as model, as it will allow you to access easily all the files. Also, a buffer model is mainly designed for models that are ready to be used in your application.
+
+Let's suppose you have a file `model.zip` stored somewhere: you unzip it in runtime and then get the access to its files as buffers. Those buffers should be available for the rest of your application run-time and you shouldn't be in need to read them every time you are going to create a pass.
 ___
 
 > Using the .pass extension is a best practice, showing that the directory is a pass package.
 > ([Build your first pass - Apple Developer Portal](https://apple.co/2LYXWo3)).
 
-Following to this best practice, the package is set to require each model to have a **_.pass_** extension.
+Following to this best practice, the package is set to require each folder-model to have a **_.pass_** extension.
-If the extension is not specified in the configuration (as in [Usage Example](#usage_example), at "model" key), it will be added forcefully.
+If omitted in the configuration (as in [Usage Example](#usage_example), at "model" key), it will be forcefully added.
 
 ___
 
@@ -55,9 +60,11 @@ Follow the [Apple Developer documentation](https://apple.co/2wuJLC1) (_Package S
 
 You can also create `.lproj` folders (e.g. *en.lproj* or *it.lproj*) containing localized media. To include a folder or translate texts inside the pass, please refer to [Localizing Passes](./API.md#method_localize) in the API documentation.
 
+To include a file that belongs to an `.lproj` folder in buffers, you'll just have to name a key like `en.lproj/thumbnail.png`.
+
 ##### Pass.json
 
-Create a `pass.json` by taking example from examples folder models or the one provided by Apple for the [first tutorial](https://apple.co/2NA2nus) and fill it with the basic informations, that is `teamIdentifier`, `passTypeIdentifier` and all the other basic keys like pass type. Please refer to [Top-Level Keys/Standard Keys](https://apple.co/2PRfSnu) and [Top-Level Keys/Style Keys](https://apple.co/2wzyL5J).
+Create a `pass.json` by taking example from examples folder models or the one provided by Apple for the [first tutorial](https://apple.co/2NA2nus) and fill it with the basic informations, that are `teamIdentifier`, `passTypeIdentifier` and all the other basic keys like pass type. Please refer to [Top-Level Keys/Standard Keys](https://apple.co/2PRfSnu) and [Top-Level Keys/Style Keys](https://apple.co/2wzyL5J).
 
 ```json
 {
@@ -113,40 +120,41 @@ ___
 
 ## Usage example
 
-```javascript
+```typescript
-const { Pass } = require("passkit-generator");
+const { createPass, Pass } = require("passkit-generator");
+// or, for typescript
+import { createPass, Pass } from "passkit-generator";
 
-let examplePass = new Pass({
+let examplePass: Pass;
-	model: "./passModels/myFirstModel",
+
-	certificates: {
+try {
-		wwdr: "./certs/wwdr.pem",
+	examplePass = await createPass({
-		signerCert: "./certs/signercert.pem",
+		model: "./passModels/myFirstModel",
-		signerKey: {
+		certificates: {
-			keyFile: "./certs/signerkey.pem",
+			wwdr: "./certs/wwdr.pem",
-			passphrase: "123456"
+			signerCert: "./certs/signercert.pem",
+			signerKey: {
+				keyFile: "./certs/signerkey.pem",
+				passphrase: "123456"
+			}
+		},
+		overrides: {
+			// keys to be added or overridden
+			serialNumber: "AAGH44625236dddaffbda"
 		}
-	},
-	overrides: {
-		// keys to be added or overridden
-		serialNumber: "AAGH44625236dddaffbda"
-	},
-	// if true, existing keys added through methods get overwritten
-	// pushed in queue otherwise.
-	shouldOverwrite: true
-});
-
-// Adding some settings to be written inside pass.json
-examplePass.localize("en", { ... });
-examplePass.barcode("36478105430"); // Random value
-
-// Generate the stream, which gets returned through a Promise
-examplePass.generate()
-	.then(stream => {
-		doSomethingWithTheStream(stream);
-	})
-	.catch(err => {
-		doSomethingWithTheError(err);
 	});
+
+	// Adding some settings to be written inside pass.json
+	examplePass.localize("en", { ... });
+	examplePass.barcode("36478105430"); // Random value
+
+	// Generate the stream, which gets returned through a Promise
+	const stream: Stream = examplePass.generate();
+
+	doSomethingWithTheStream(stream);
+} catch (err) {
+	doSomethingWithTheError(err);
+}
 ```
 
 ___
@@ -157,7 +165,7 @@ If you used this package in any of your projects, feel free to open a topic in i
 
 The idea to develop this package, was born during the Apple Developer Academy 17/18, in Naples, Italy, driven by the need to create an iOS app component regarding passes generation for events.
 
-A big thanks to all the people and friends in the Apple Developer Academy (and not) that pushed me and helped me into realizing something like this and a big thanks to the ones that helped me to make technical choices.
+A big thanks to all the people and friends in the Apple Developer Academy (and not) that pushed me and helped me into realizing something like this and a big thanks to the ones that helped me to make technical choices and to all the contributors.
 
 Any contribution, is welcome.
 Made with ❤️ in Italy.