{"id":19123000,"url":"https://github.com/digitalbazaar/payswarm.js","last_synced_at":"2025-05-05T18:29:36.816Z","repository":{"id":3649172,"uuid":"4716873","full_name":"digitalbazaar/payswarm.js","owner":"digitalbazaar","description":"A PaySwarm client for node.js","archived":false,"fork":false,"pushed_at":"2014-10-08T18:12:44.000Z","size":759,"stargazers_count":19,"open_issues_count":2,"forks_count":1,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-17T09:02:32.307Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://payswarm.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalbazaar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-06-19T17:24:54.000Z","updated_at":"2023-10-04T05:00:54.000Z","dependencies_parsed_at":"2022-08-18T18:21:44.847Z","dependency_job_id":null,"html_url":"https://github.com/digitalbazaar/payswarm.js","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fpayswarm.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fpayswarm.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fpayswarm.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fpayswarm.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalbazaar","download_url":"https://codeload.github.com/digitalbazaar/payswarm.js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252552745,"owners_count":21766758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T05:23:54.862Z","updated_at":"2025-05-05T18:29:36.796Z","avatar_url":"https://github.com/digitalbazaar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"payswarm.js\n===========\n\nThe [PaySwarm][] Client API enables software to interact with a PaySwarm\nAuthority. This includes registering public/private keypairs, performing\npurchases, depositing money, and withdrawing money into a bank account.\n\nInstallation\n------------\n\npayswarm.js is available via github and npm:\n\n* github: https://github.com/digitalbazaar/payswarm.js\n* npm: https://npmjs.org/package/payswarm\n\nCommand Line Tool\n-----------------\n\nA tool is included that allows command line access to various PaySwarm\nAuthority features. For a list of tools and tool help, use the following:\n\n    ./bin/payswarm -h\n    ./bin/payswarm {toolname} -h\n\nMost tools require authorization via an access key that is based on a public\nand private keypair. This key, the associated authority URL, and other\nvalues are stored in a configuration file. Tools allow you to select the\nactive config file so you may have multiple keys from a single or many\nauthorities.\n\nAfter you have created an identity on an authority you can generate and\nregister an access key:\n\n    ./bin/payswarm keys -r -a {authority-url}\n\nWithout the `-a` option this will default to the sandbox authority. Use the\n`-c` option with any tool if you wish to specify a config file other than\n`payswarm.cfg`.  Once you have an access key, the tools will use this to\nauthorize you to an authority.\n\nTo list your keys, show a key by id, or show a key by short id:\n\n    ./bin/payswarm keys\n    ./bin/payswarm keys https://example.com/i/{my-id}/keys/1\n    ./bin/payswarm keys 1\n\nTo perform a purchase of a listing (**NOTE**: This performs a real purchase\nusing a real account!):\n\n    ./bin/payswarm purchase {listing-url}\n\nDevelopers may be interested in the curl-like tool used to perform\nauthorized raw REST access on authority URLs. The HTTP method and body data\ncan be specified. (**NOTE**: This tool performs raw PaySwarm Authority\naccess without user friendly guidance or confirmations. Be careful!) For\nexample, to get all of your account details in JSON-LD format:\n\n    ./bin/payswarm url https://example.com/i/{my-id}/accounts\n\nA tool useful for development is the `info` tool. It will print out framed\nassets, licenses, listings, and hashes:\n\n    ./bin/payswarm info {listing-url}\n\nThe `jsonld` tool from the [jsonld.js][] project can be useful for more\nadvanced JSON-LD manipulation. To print key details in normalized N-Quads\nformat:\n\n    ./bin/payswarm keys 1 | jsonld normalize -q\n\nTo sign or verify raw JSON-LD data, use the `signature` tool. For instance, to sign and verify a string of JSON-LD using the registered private key from a config file:\n\n    ./bin/payswarm signature --config local.cfg --sign '{\"@context\": \"https://w3id.org/payswarm/v1\", \"@id\": \"http://example.com/id/1\", \"http://example.com/foo\": \"bar\"}' | ./bin/payswarm signature --verify @-\n\n\nAPI Introduction\n----------------\n\nWhen writing software intended to act as a PaySwarm Buyer (something that\nmakes purchases on the Web) or PaySwarm Vendor (something that sells stuff\non the Web), the developer must do the following:\n\n1. Implement application-specific hooks for fetching documents from the Web,\n   caching those documents, and storing sensitive data.\n2. Create a white-list of all trusted PaySwarm Authorities.\n3. Implement the public/private key-pair creation and registration UI.\n4. If creating buyer software, implement the software purchasing UI and\n   calls to process the purchase via a PaySwarm Authority.\n5. If creating vendor software, implement the software sales UI, asset and\n   listing creation UI, and all the calls to initiate a purchase via a\n   PaySwarm Authority.\n\nImplementing Hooks\n------------------\n\nVarious hooks will be triggered when making calls to the API. Most of the\nhooks involve providing the API with a custom mechanism for doing HTTP\nGET/POST and storing/retrieving data from a database.  It is also highly\nrecommended that the optional cache hooks be implemented to prevent\nexcessive network traffic when looking up PaySwarm Authority configurations\nand public keys. To implement a hook, simply write a function that takes the\nappropriate parameters and returns the appropriate values. Then pass the\nhook name and the name of the custom function to 'payswarm.addHook'. Look\nbelow for the specific hooks that must be implemented.\n\nImporting the Client\n--------------------\n\nAt the top of your implementation, require the PaySwarm Client API:\n\n```javascript\nvar payswarm = require('payswarm');\n```\n\nAdding Trusted PaySwarm Authorities\n-----------------------------------\n\nAdd the PaySwarm Authorities that should be trusted by calling:\n\n```javascript\npayswarm.addTrustedAuthority('trustedauthority:port');\n```\n\nIn this version of the API, any PaySwarm Authority that the software will\ninteract with must be manually added. A vendor's chosen PaySwarm Authority\nwill be automatically added during the registration step. In the future,\nthere will be a registry of trusted PaySwarm Authorities.\n\nPerforming a Purchase\n---------------------\n\n\nVendor Registration\n-------------------\n\nIf you are implementing a website that will operate as a PaySwarm Vendor (a\npiece of software that is selling something on the Web), you may register\nthe vendor by calling:\n\n```javascript\nvar url = payswarm.getRegisterVendorUrl(\n  'myauthority:port',\n  'http://myserver/myregistercallbackurl',\n  callback);\n```\n\nThe first parameter is the host and port of the PaySwarm Authority to\nregister with. The second is a callback URL that will receive the result of\nthe registration as POST data.\n\nDirect the vendor to the URL so that they can complete the registration\nprocess. Once the registration process is complete, the vendor's browser\nwill POST the registration result to the callback URL provided.\n\nOn the callback page, get the POST value 'encrypted-message' and pass it to\nregister the vendor:\n\n```javascript\npayswarm.registerVendor(req.body['encrypted-message'], callback);\n```\n\nIf no error is given to the callback, registration is complete. The second\ncallback parameter is the PaySwarm Vendor's Preferences, including the\nFinancial Account ID to use in Listings.\n\nCreating Assets and Listings\n----------------------------\n\nCreate a JSON-LD PaySwarm Asset and Listing. When listing an Asset, its\nunique hash must be in the Listing. To generate an asset hash call:\n\n```javascript\npayswarm.hash(asset, callback);\n```\n\nSign a listing. Create a JSON-LD PaySwarm Listing and then sign it:\n\n```javascript\npayswarm.sign(listing, callback);\n```\n\n  Display the listing information; the use of RDFa is recommended. Depending\n  on the application's needs, it is sometimes a good idea (or a requirement)\n  to regenerate signatures when the vendor's public key is changed.\n\n  Note: A Listing also contains a License for the Asset. If the application\n  knows the ID (IRI) of the License to use but not the License hash, and it\n  does not have the necessary parser to obtain the License information from\n  its ID, it may use the PaySwarm Authority's license service to cache and\n  retrieve the License by its ID. Then payswarm.hash(license, callback) can\n  be called on the result to produce its hash.\n\nPerforming a Vendor-initiated Purchase\n--------------------------------------\n\nWhen a customer indicates that they want to purchase the Asset in a Listing,\ncall:\n\n```javascript\nvar url = payswarm.getPurchaseUrl(\n  'customersauthority:port',\n  listingId,\n  listingHash,\n  'https://myserver/mypurchasecallbackurl',\n  callback);\n```\n\nTo get a URL to redirect the customer to their PaySwarm Authority to\ncomplete the purchase. The last parameter is a callback URL that will\nreceive the result of the purchase as POST data.\n\nIf the customer has previously completed a purchase and the response\nindicated that they set up a budget to handle automated purchases in the\nfuture, then an automated purchase can be attempted by calling:\n\n```javascript\npayswarm.purchase(\n  'customersauthority:port',\n  'https://customersauthority:port/i/customer',\n  listingId,\n  listingHash,\n  callback);\n```\n\nIn this version of the API, it is the responsibility of the application to\ndetermine the customer's PaySwarm Authority (usually by asking). A listing\nhash can be generated by calling:\n\n```javascript\npayswarm.hash(listing, callback);\n```\n\nTo get the JSON-LD receipt from a purchase, call:\n\n```javascript\npayswarm.getReceipt(encryptedMessage, callback);\n```\n\nWhere encryptedMessage is either the result of a POST to the purchase\ncallback or the result of the `payswarm.purchase()` call.\n\nThe receipt will indicate the ID and hash of the Asset purchased as well as\nthe ID and hash of the License for the Asset.\n\nAuthors\n-------\n\nThis software was written by [Digital Bazaar][] and friends. Please see the\n[AUTHORS][] file for full credits.\n\nLicense\n-------\n\nThe payswarm.js code, tools, and examples are available under a BSD 3-Clause\nLicense. Please see the [LICENSE][] file for full details.\n\n[PaySwarm]: http://payswarm.com/\n[Digital Bazaar]: http://digitalbazaar.com/\n[AUTHORS]: AUTHORS\n[LICENSE]: LICENSE\n[jsonld.js]: https://github.com/digitalbazaar/jsonld.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fpayswarm.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalbazaar%2Fpayswarm.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fpayswarm.js/lists"}