diff --git a/dist/plugins/contacts.d.ts b/dist/plugins/contacts.d.ts index c38e6ca3..48ed9f94 100644 --- a/dist/plugins/contacts.d.ts +++ b/dist/plugins/contacts.d.ts @@ -1,8 +1,108 @@ +export interface ContactProperties { + /** A globally unique identifier. */ + id?: string; + /** The name of this Contact, suitable for display to end users. */ + displayName?: string; + /** An object containing all components of a persons name. */ + name?: ContactName; + /** A casual name by which to address the contact. */ + nickname?: string; + /** An array of all the contact's phone numbers. */ + phoneNumbers?: ContactField[]; + /** An array of all the contact's email addresses. */ + emails?: ContactField[]; + /** An array of all the contact's addresses. */ + addresses?: ContactAddress[]; + /** An array of all the contact's IM addresses. */ + ims?: ContactField[]; + /** An array of all the contact's organizations. */ + organizations?: ContactOrganization[]; + /** The birthday of the contact. */ + birthday?: Date; + /** A note about the contact. */ + note?: string; + /** An array of the contact's photos. */ + photos?: ContactField[]; + /** An array of all the user-defined categories associated with the contact. */ + categories?: ContactField[]; + /** An array of web pages associated with the contact. */ + urls?: ContactField[]; +} +export interface Contact extends ContactProperties { + /** + * Returns a new Contact object that is a deep copy of the calling object, with the id property set to null + */ + clone(): Contact; + /** + * Removes the contact from the device contacts database, otherwise executes an error callback with a ContactError object. + * @param onSuccess Success callback function invoked on success operation. + * @param onError Error callback function, invoked when an error occurs. + */ + remove(onSuccess?: () => void, onError?: (error: Error) => void): void; + /** + * Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists. + * @param onSuccess Success callback function invoked on success operation with che Contact object. + * @param onError Error callback function, invoked when an error occurs. + */ + save(onSuccess?: (contact: Contact) => void, onError?: (error: Error) => void): void; +} +export interface ContactName { + /** The complete name of the contact. */ + formatted?: string; + /** The contact's family name. */ + familyName?: string; + /** The contact's given name. */ + givenName?: string; + /** The contact's middle name. */ + middleName?: string; + /** The contact's prefix (example Mr. or Dr.) */ + honorificPrefix?: string; + /** The contact's suffix (example Esq.). */ + honorificSuffix?: string; +} +export interface ContactField { + /** A string that indicates what type of field this is, home for example. */ + type: string; + /** The value of the field, such as a phone number or email address. */ + value: string; + /** Set to true if this ContactField contains the user's preferred value. */ + pref: boolean; +} +export interface ContactAddress { + /** Set to true if this ContactAddress contains the user's preferred value. */ + pref?: boolean; + /** A string indicating what type of field this is, home for example. */ + type?: string; + /** The full address formatted for display. */ + formatted?: string; + /** The full street address. */ + streetAddress?: string; + /** The city or locality. */ + locality?: string; + /** The state or region. */ + region?: string; + /** The zip code or postal code. */ + postalCode?: string; + /** The country name. */ + country?: string; +} +export interface ContactOrganization { + /** Set to true if this ContactOrganization contains the user's preferred value. */ + pref?: boolean; + /** A string that indicates what type of field this is, home for example. */ + type?: string; + /** The name of the organization. */ + name?: string; + /** The department the contract works for. */ + department?: string; + /** The contact's title at the organization. */ + title?: string; +} /** * Access and manage Contacts on the device. * * Requires plugin: `cordova-plugin-contacts` - * For full info, please see the [Cordova Contacts Docs](https://github.com/apache/cordova-plugin-contacts) + * For full info, please see the [Cordova Contacts plugin docs](https://github.com/apache/cordova-plugin-contacts) * * @usage * @@ -16,7 +116,34 @@ * */ export declare class Contacts { - static create(fields: string[], options: any): void; - static find(fields: string[], options: any): void; - static pickContact(): void; + /** + * Create a new Contact object. + * + * @param options {Object} Object whose properties the created Contact should have. + * @return {Contact} Returns the created contact + */ + static create(options: ContactProperties): Contact; + /** + * Search for contacts in the Contacts list. + * + * Example: Contacts.find(['*'], { filter: 'Max' }) // will search for a displayName of 'Max' + * + * @param fields {string[]} Contact fields to be used as a search qualifier. + * A zero-length contactFields parameter is invalid and results in ContactError.INVALID_ARGUMENT_ERROR. + * A contactFields value of "*" searches all contact fields. + * + * @param options {Object} the options to query with: + * filter: The search string used to find navigator.contacts. (string) (Default: "") + * multiple: Determines if the find operation returns multiple navigator.contacts. (Boolean) (Default: false) + * desiredFields: Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields. (DOMString[]) [Optional] + * hasPhoneNumber(Android only): Filters the search to only return contacts with a phone number informed. (Boolean) (Default: false) + * + * @return Returns a Promise that resolves with the search results (an array of Contact objects) + */ + static find(fields: string[], options?: any): Promise; + /** + * Select a single Contact. + * @return Returns a Promise that resolves with the selected Contact + */ + static pickContact(): Promise; } diff --git a/dist/plugins/contacts.js b/dist/plugins/contacts.js index 64eb4c73..fdabbf48 100644 --- a/dist/plugins/contacts.js +++ b/dist/plugins/contacts.js @@ -9,7 +9,7 @@ var plugin_1 = require('./plugin'); * Access and manage Contacts on the device. * * Requires plugin: `cordova-plugin-contacts` - * For full info, please see the [Cordova Contacts Docs](https://github.com/apache/cordova-plugin-contacts) + * For full info, please see the [Cordova Contacts plugin docs](https://github.com/apache/cordova-plugin-contacts) * * @usage * @@ -25,16 +25,48 @@ var plugin_1 = require('./plugin'); var Contacts = (function () { function Contacts() { } - Contacts.create = function (fields, options) { }; + /** + * Create a new Contact object. + * + * @param options {Object} Object whose properties the created Contact should have. + * @return {Contact} Returns the created contact + */ + Contacts.create = function (options) { + return new Contact(); + }; ; - Contacts.find = function (fields, options) { }; + /** + * Search for contacts in the Contacts list. + * + * Example: Contacts.find(['*'], { filter: 'Max' }) // will search for a displayName of 'Max' + * + * @param fields {string[]} Contact fields to be used as a search qualifier. + * A zero-length contactFields parameter is invalid and results in ContactError.INVALID_ARGUMENT_ERROR. + * A contactFields value of "*" searches all contact fields. + * + * @param options {Object} the options to query with: + * filter: The search string used to find navigator.contacts. (string) (Default: "") + * multiple: Determines if the find operation returns multiple navigator.contacts. (Boolean) (Default: false) + * desiredFields: Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields. (DOMString[]) [Optional] + * hasPhoneNumber(Android only): Filters the search to only return contacts with a phone number informed. (Boolean) (Default: false) + * + * @return Returns a Promise that resolves with the search results (an array of Contact objects) + */ + Contacts.find = function (fields, options) { + return new Promise(function (res, rej) { }); + }; ; - Contacts.pickContact = function () { }; + /** + * Select a single Contact. + * @return Returns a Promise that resolves with the selected Contact + */ + Contacts.pickContact = function () { + return new Promise(function (res, rej) { }); + }; ; __decorate([ plugin_1.Cordova({ - successIndex: 1, - errorIndex: 2 + sync: true }) ], Contacts, "create", null); __decorate([ diff --git a/dist/plugins/contacts.js.map b/dist/plugins/contacts.js.map index 2e8a19bd..4022148d 100644 --- a/dist/plugins/contacts.js.map +++ b/dist/plugins/contacts.js.map @@ -1 +1 @@ -{"version":3,"file":"contacts.js","sourceRoot":"","sources":["../../src/plugins/contacts.ts"],"names":["Contacts","Contacts.constructor","Contacts.create","Contacts.find","Contacts.pickContact"],"mappings":";;;;;;AAAA,uBAA8B,UAAU,CAAC,CAAA;AAEzC;;;;;;;;;;;;;;;;GAgBG;AAEH;IAAAA;IA+DAC,CAACA;IAzBQD,eAAMA,GA/BbA,UA+BcA,MAAeA,EAAEA,OAAWA,IAAEE,CAACA;;IAqBtCF,aAAIA,GAnBXA,UAmBYA,MAAeA,EAAEA,OAAWA,IAAEG,CAACA;;IAGpCH,oBAAWA,GADlBA,cACqBI,CAACA;;IAvDtBJ;QAACA,gBAAOA,CAACA;YACPA,YAAYA,EAAEA,CAACA;YACfA,UAAUA,EAAEA,CAACA;SACdA,CAACA;OA4BKA,kBAAMA,QAAgCA;IAE7CA;QAACA,gBAAOA,CAACA;YACPA,YAAYA,EAAEA,CAACA;YACfA,UAAUA,EAAEA,CAACA;SACdA,CAACA;OAgBKA,gBAAIA,QAAgCA;IAE3CA;QAACA,gBAAOA,EAAEA;OACHA,uBAAWA,QAAIA;IA9DxBA;QAACA,eAAMA,CAACA;YACNA,IAAIA,EAAEA,UAAUA;YAChBA,MAAMA,EAAEA,yBAAyBA;YACjCA,SAASA,EAAEA,oBAAoBA;YAC/BA,IAAIA,EAAEA,mDAAmDA;SAC1DA,CAACA;iBA0DDA;IAADA,eAACA;AAADA,CAACA,AA/DD,IA+DC;AAzDY,gBAAQ,WAyDpB,CAAA"} \ No newline at end of file +{"version":3,"file":"contacts.js","sourceRoot":"","sources":["../../src/plugins/contacts.ts"],"names":["Contacts","Contacts.constructor","Contacts.create","Contacts.find","Contacts.pickContact"],"mappings":";;;;;;AAAA,uBAA8B,UAAU,CAAC,CAAA;AA6LzC;;;;;;;;;;;;;;;;GAgBG;AACH;IAAAA;IAqDAC,CAACA;IA9CCD;;;;;OAKGA;IAIIA,eAAMA,GAHbA,UAGcA,OAA0BA;QACtCE,MAAMA,CAACA,IAAIA,OAAOA,EAAEA,CAACA;IACvBA,CAACA;;IAEDF;;;;;;;;;;;;;;;;OAgBGA;IAKIA,aAAIA,GAJXA,UAIYA,MAAgBA,EAAEA,OAAaA;QACzCG,MAAMA,CAACA,IAAIA,OAAOA,CAAYA,UAACA,GAAGA,EAAEA,GAAGA,IAAMA,CAACA,CAACA,CAACA;IAClDA,CAACA;;IAEDH;;;OAGGA;IAEIA,oBAAWA,GADlBA;QAEEI,MAAMA,CAACA,IAAIA,OAAOA,CAAUA,UAACA,GAAGA,EAAEA,GAAGA,IAAMA,CAACA,CAACA,CAACA;IAChDA,CAACA;;IAvCDJ;QAACA,gBAAOA,CAACA;YACPA,IAAIA,EAAEA,IAAIA;SACXA,CAACA;OACKA,kBAAMA,QAEZA;IAmBDA;QAACA,gBAAOA,CAACA;YACPA,YAAYA,EAAEA,CAACA;YACfA,UAAUA,EAAEA,CAACA;SACdA,CAACA;OACKA,gBAAIA,QAEVA;IAMDA;QAACA,gBAAOA,EAAEA;OACHA,uBAAWA,QAEjBA;IApDHA;QAACA,eAAMA,CAACA;YACNA,IAAIA,EAAEA,UAAUA;YAChBA,MAAMA,EAAEA,yBAAyBA;YACjCA,SAASA,EAAEA,oBAAoBA;YAC/BA,IAAIA,EAAEA,mDAAmDA;SAC1DA,CAACA;iBAgDDA;IAADA,eAACA;AAADA,CAACA,AArDD,IAqDC;AA/CY,gBAAQ,WA+CpB,CAAA"} \ No newline at end of file diff --git a/src/plugins/contacts.ts b/src/plugins/contacts.ts index e81487ff..68a25739 100644 --- a/src/plugins/contacts.ts +++ b/src/plugins/contacts.ts @@ -1,10 +1,197 @@ import {Plugin, Cordova} from './plugin'; +export interface ContactProperties { + /** A globally unique identifier. */ + id?: string; + /** The name of this Contact, suitable for display to end users. */ + displayName?: string; + /** An object containing all components of a persons name. */ + name?: ContactName; + /** A casual name by which to address the contact. */ + nickname?: string; + /** An array of all the contact's phone numbers. */ + phoneNumbers?: ContactField[]; + /** An array of all the contact's email addresses. */ + emails?: ContactField[]; + /** An array of all the contact's addresses. */ + addresses?: ContactAddress[]; + /** An array of all the contact's IM addresses. */ + ims?: ContactField[]; + /** An array of all the contact's organizations. */ + organizations?: ContactOrganization[]; + /** The birthday of the contact. */ + birthday?: Date; + /** A note about the contact. */ + note?: string; + /** An array of the contact's photos. */ + photos?: ContactField[]; + /** An array of all the user-defined categories associated with the contact. */ + categories?: ContactField[]; + /** An array of web pages associated with the contact. */ + urls?: ContactField[]; +} + +export interface Contact extends ContactProperties { + /** + * Returns a new Contact object that is a deep copy of the calling object, with the id property set to null + */ + clone(): Contact; + /** + * Removes the contact from the device contacts database, otherwise executes an error callback with a ContactError object. + * @param onSuccess Success callback function invoked on success operation. + * @param onError Error callback function, invoked when an error occurs. + */ + remove( + onSuccess?: () => void, + onError?: (error: Error) => void): void; + /** + * Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists. + * @param onSuccess Success callback function invoked on success operation with che Contact object. + * @param onError Error callback function, invoked when an error occurs. + */ + save( + onSuccess?: (contact: Contact) => void, + onError?: (error: Error) => void): void; +} + +interface ContactError { + /** Error code */ + code: number; + /** Error message */ + message: string; +} + +declare var ContactError: { + new(code: number): ContactError; + UNKNOWN_ERROR: number; + INVALID_ARGUMENT_ERROR: number; + TIMEOUT_ERROR: number; + PENDING_OPERATION_ERROR: number; + IO_ERROR: number; + NOT_SUPPORTED_ERROR: number; + PERMISSION_DENIED_ERROR: number +}; + +export interface ContactName { + /** The complete name of the contact. */ + formatted?: string; + /** The contact's family name. */ + familyName?: string; + /** The contact's given name. */ + givenName?: string; + /** The contact's middle name. */ + middleName?: string; + /** The contact's prefix (example Mr. or Dr.) */ + honorificPrefix?: string; + /** The contact's suffix (example Esq.). */ + honorificSuffix?: string; +} + +declare var ContactName: { + /** Constructor for ContactName object */ + new(formatted?: string, + familyName?: string, + givenName?: string, + middleName?: string, + honorificPrefix?: string, + honorificSuffix?: string): ContactName +}; + +export interface ContactField { + /** A string that indicates what type of field this is, home for example. */ + type: string; + /** The value of the field, such as a phone number or email address. */ + value: string; + /** Set to true if this ContactField contains the user's preferred value. */ + pref: boolean; +} + +declare var ContactField: { + /** Constructor for ContactField object */ + new(type?: string, + value?: string, + pref?: boolean): ContactField +}; + +export interface ContactAddress { + /** Set to true if this ContactAddress contains the user's preferred value. */ + pref?: boolean; + /** A string indicating what type of field this is, home for example. */ + type?: string; + /** The full address formatted for display. */ + formatted?: string; + /** The full street address. */ + streetAddress?: string; + /** The city or locality. */ + locality?: string; + /** The state or region. */ + region?: string; + /** The zip code or postal code. */ + postalCode?: string; + /** The country name. */ + country?: string; +} + +declare var ContactAddress: { + /** Constructor of ContactAddress object */ + new(pref?: boolean, + type?: string, + formatted?: string, + streetAddress?: string, + locality?: string, + region?: string, + postalCode?: string, + country?: string): ContactAddress +}; + +export interface ContactOrganization { + /** Set to true if this ContactOrganization contains the user's preferred value. */ + pref?: boolean; + /** A string that indicates what type of field this is, home for example. */ + type?: string; + /** The name of the organization. */ + name?: string; + /** The department the contract works for. */ + department?: string; + /** The contact's title at the organization. */ + title?: string; +} + +declare var ContactOrganization: { + /** Constructor for ContactOrganization object */ + new(pref?: boolean, + type?: string, + name?: string, + department?: string, + title?: string): ContactOrganization +}; + +/** Search options to filter navigator.contacts. */ +interface ContactFindOptions { + /** The search string used to find navigator.contacts. */ + filter?: string; + /** Determines if the find operation returns multiple navigator.contacts. */ + multiple?: boolean; + /* Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields. */ + desiredFields?: string[]; +} + +declare var ContactFindOptions: { + /** Constructor for ContactFindOptions object */ + new(filter?: string, + multiple?: boolean, + desiredFields?: string[]): ContactFindOptions +}; + +declare var Contact: { + new(): Contact +} + /** * Access and manage Contacts on the device. * * Requires plugin: `cordova-plugin-contacts` - * For full info, please see the [Cordova Contacts Docs](https://github.com/apache/cordova-plugin-contacts) + * For full info, please see the [Cordova Contacts plugin docs](https://github.com/apache/cordova-plugin-contacts) * * @usage * @@ -17,7 +204,6 @@ import {Plugin, Cordova} from './plugin'; * See the `save()` docs for a full list of fields. * */ - @Plugin({ name: 'Contacts', plugin: 'cordova-plugin-contacts', @@ -25,60 +211,50 @@ import {Plugin, Cordova} from './plugin'; repo: 'https://github.com/apache/cordova-plugin-contacts' }) export class Contacts { + /** + * Create a new Contact object. + * + * @param options {Object} Object whose properties the created Contact should have. + * @return {Contact} Returns the created contact + */ + @Cordova({ + sync: true + }) + static create(options: ContactProperties){ + return new Contact(); + }; + + /** + * Search for contacts in the Contacts list. + * + * Example: Contacts.find(['*'], { filter: 'Max' }) // will search for a displayName of 'Max' + * + * @param fields {string[]} Contact fields to be used as a search qualifier. + * A zero-length contactFields parameter is invalid and results in ContactError.INVALID_ARGUMENT_ERROR. + * A contactFields value of "*" searches all contact fields. + * + * @param options {Object} the options to query with: + * filter: The search string used to find navigator.contacts. (string) (Default: "") + * multiple: Determines if the find operation returns multiple navigator.contacts. (Boolean) (Default: false) + * desiredFields: Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields. (DOMString[]) [Optional] + * hasPhoneNumber(Android only): Filters the search to only return contacts with a phone number informed. (Boolean) (Default: false) + * + * @return Returns a Promise that resolves with the search results (an array of Contact objects) + */ @Cordova({ successIndex: 1, errorIndex: 2 }) + static find(fields: string[], options?: any){ + return new Promise((res, rej) => {}); + }; -/** - * Save a contact into the contacts database. - * - * Valid fields: - * { - * id: A globally unique identifier. (DOMString) - * displayName: The name of this Contact, suitable for display to end-users. (DOMString) - * name: An object containing all components of a persons name. (ContactName) - * nickname: A casual name by which to address the contact. (DOMString) - * phoneNumbers: An array of all the contact's phone numbers. (ContactField[]) - * emails: An array of all the contact's email addresses. (ContactField[]) - * addresses: An array of all the contact's addresses. (ContactAddress[]) - * ims: An array of all the contact's IM addresses. (ContactField[]) - * organizations: An array of all the contact's organizations. (ContactOrganization[]) - * birthday: The birthday of the contact. (Date) - * note: A note about the contact. (DOMString) - * photos: An array of the contact's photos. (ContactField[]) - * categories: An array of all the user-defined categories associated with the contact. (ContactField[]) - * urls: An array of web pages associated with the contact. (ContactField[]) - * } - * - * @param contact {object} the contact to save. - * @return {Promise} that resolves with the created and saved contact - */ - - // This method is create(fields, success, error, options) :/ - static create(fields:string[], options:any){}; - - @Cordova({ - successIndex: 1, - errorIndex: 2 - }) - -/** - * Search for contacts in the Contacts list. - * - * Example: Contacts.find({ filter: 'Max' }) // will search for a displayName of 'Max' - * - * @param options the options to query with - * - * filter: The search string used to find navigator.contacts. (DOMString) (Default: "") - * multiple: Determines if the find operation returns multiple navigator.contacts. (Boolean) (Default: false) - * desiredFields: Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields. (DOMString[]) [Optional] - * hasPhoneNumber(Android only): Filters the search to only return contacts with a phone number informed. (Boolean) (Default: false) - * - * @return {Promise} that resolves with the search results - */ - static find(fields:string[], options:any){}; - + /** + * Select a single Contact. + * @return Returns a Promise that resolves with the selected Contact + */ @Cordova() - static pickContact(){}; + static pickContact(){ + return new Promise((res, rej) => {}); + }; }