{"id":18558033,"url":"https://github.com/zh/collecta-xmpp","last_synced_at":"2025-04-10T01:32:39.415Z","repository":{"id":707276,"uuid":"353832","full_name":"zh/collecta-xmpp","owner":"zh","description":"Ruby library for easy working with the Collecta XMPP API","archived":false,"fork":false,"pushed_at":"2009-12-11T04:27:26.000Z","size":97,"stargazers_count":20,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T14:38:27.727Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://developer.collecta.com/XmppApi/","language":"Ruby","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zh.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-10-29T07:00:27.000Z","updated_at":"2013-10-08T06:02:37.000Z","dependencies_parsed_at":"2022-07-07T15:01:13.456Z","dependency_job_id":null,"html_url":"https://github.com/zh/collecta-xmpp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fcollecta-xmpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fcollecta-xmpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fcollecta-xmpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fcollecta-xmpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zh","download_url":"https://codeload.github.com/zh/collecta-xmpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248140754,"owners_count":21054349,"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-06T21:38:43.150Z","updated_at":"2025-04-10T01:32:34.399Z","avatar_url":"https://github.com/zh.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Collecta XMPP API Ruby Library\n\nRuby library for easy working with the [Collecta XMPP API](http://developer.collecta.com/XmppApi/).\n\n## Required gems and libraries\n\n * _xmpp4r_ - low level XMPP manipulations\n * _crack_ - XML parsing\n * _switchboard_ - only for collecta_jack.rb\n * _xmpp4-simple_ - only for collecta_bot.rb\n * _eventmachine_ - only for collecta_bot.rb\n * _sinatra_ - only for collecta_web.rb\n * _json_ - only for collecta_web.rb\n\n## Implemented features\n\n### collecta.rb\n\n * _Jabber::PubSub::ServiceHelper::subscribe\\_to\\_with\\_options()_ function for passing Data Forms option on node subscription\n * _Collecta::Client_ (inheriting _Jabber::Client_) for SASL ANONYMOUS connection, PubSub (un)subscription etc.\n * _Collecta::Payload_ class, encapsulating Collecta Messages (XML to Hash conversion is done via [Crack](http://github.com/jnunemaker/crack)\n\n### collecta_jack.rb\n\n * _Switchboard::AnonymousClient_ (inheriting _Switchboard::Client_) for SASL ANONYMOUS connection\n * _Switchboard::CollectaClient_ (inheriting _Switchboard::AnonymousClient_) and adding Collecta default settings (service URL, node etc.)\n * _CollectaJack_ - [Switchboard Jack](http://mojodna.net/2009/07/19/switchboard-as-a-framework.html) for PubSub subscription etc.\n\n_test\\_search.rb_ and _test\\_jack.rb_ for library testing and  demonstration.\n\n### collecta_bot.rb\n\n * _Collecta::Task_ - EventMachine::Deferrable - based - background processing for long-running tasks\n * _Collecta::Bot_  - EventMachine -based XMPP bot, sending results from the Collecta searches to some JID\n\n### collecta_web.rb\n\n * _Collecta::App_ - Sinatra-based simple web API (inheriting _Sinatra::Default_)\n\n\n## Usage\n\nDownload the library from the [GitHub repository](http://github.com/zh/collecta-xmpp) and copy all files inside your project's sources directory.\nBe sure to pass your [Collecta API key](http://developer.collecta.com/KeyRequest/) on the _Collecta::Client.connect()_ function invoking.\n\n### Working directly with xmpp4r\n\n    require 'collecta'\n\n    apikey = \"...\"\n    query, notify = \"iphone\", \"apple, mac\"\n\n    @client = Collecta::Client.new(apikey)\n    @client.anonymous_connect\n    # search for 'iphone' and notifications for 'apple' and 'mac'\n    @client.subscribe(query, notify)\n    @client.add_message_callback do |msg|\n        next unless payload = Collecta::Payload.new(msg)\n        # do something with the messages\n    end\n    ...\n    at_exit do\n        @client.unsubscribe\n        @client.close\n    end\n\n### Working with switchboard\n\n    require 'collecta_jack'\n    \n    settings = YAML.load(File.read(\"config.yml\"))\n    # query from the command line, no notifications, debug enabled\n    switchboard = Switchboard::CollectaClient.new(settings[\"collecta.apikey\"], ARGV.pop, nil, true)\n    \n    switchboard.on_collecta_message do |msg|\n        payload = Collecta::Payload.new(msg)\n        # do something with the messages\n    end\n     \n    switchboard.run!\n\n### XMPP Bot\n\nAvailable Bot Commands\n\n * __HELP__ - just a commands list. TODO: better help message with commands description\n * __PING__ - check the connection. Will ask also for authentication\n * __S, s__ - subscribe to some query. Will start sending the results to the console JID (\"bot.console\")\n * __N, n__ - subscribe to notify. TODO: announce the notify results only when ask for them\n * __UN, un, U, u__ - unsubscribe from ALL subscriptions\n\nMake sure you have the correct settings for your bot JID and password (\"bot.jid\" and \"bot.password\")\nand for the account, that will receive all messages (\"bot.console\")\n\n    require 'collecta_bot'\n\n    class SearchBot \u003c Collecta::Bot\n        def self.format_result(msg, debug = true)\n            # some fancy message formatting\n            ...\n        end\n    end\n\n    SearchBot.run(\"config.yml\")\n    \n\n### Desktop notifications (Growl, libnotify) \n\n_collecta\\_notifyio.rb_\n\nDesktop notifications via http://notify.io/ service are also available. You can use the original \n[Growl client for Mac](http://www.notify.io/download/notifyio-client.py) or\nmy [python-notify based client for Linux](http://github.com/zh/wip/blob/master/python/notifyio-notify.py).\n\nBe sure to adjust _notifyio.userhash_ and _notifyio.apikey_ in the config file. You can get their values from\nthe [notify.io settings page](http://www.notify.io/dashboard/settings).\n\nYou need to supply the search query via the command line parameter:\n\n    $ ruby ./collecta_notifyio.rb \"iphone category:story\"\n\n\n### Simple web API (Sinatra application)\n\n_collecta\\_web.rb_\n\nThe API is not designed to be full featured web service. His primary goal is to be a backend for the main web service, \ndeployed on Google AppEngine or Heroku. The main service need to take care for the users authentication and management,\nsaving queries per user etc. But because most of the deployment environments (GAE, Heroku etc.) cannot work with\nXMPP PubSub, the current simple web API will be used for the real requests to the Collecta XMPP API.\nThe only protection in the moment is the _sig_ parameter (signature), send with each request. The signature is generated\nas follows:\n\n    sig = Digest::SHA1.hexdigest(\"--#{CFG['web.apikey']}--#{jid}\") \n    # example\n    web.apikey = \"SomeSecret\"\n    jid = \"me@jabber.org\"\n    sig = \"3dbc8601b2fd476b3eee59814d1a6ba8328e5492\"\n\nOn the server side _web.apikey_ must be set inside the _config.yml_ . For example:\n\n    # --- config.yml\n    ....\n    web.apikey: SomeSecret\n    bot.jid: bot@example.com\n    ....\n\nThe API contains just two POST requests methods ( _/1/sub/_  and _/1/unsub/_ for subscription to some query and unsubscription \nfrom all queries) and one GET request method ( _/1/list_ ) for some JID subscriptions listing. \n\nRequired parameters:\n\n * _jid_ - JID on the account, that will recieve the results from the search\n * _sig_ - signature - created as _Digest::SHA1.hexdigest()_ of _web.apikey_ from the _config.yml_ configuration file and _jid_\n * _q_ - Collecta query string (only for subscriptions - _/1/sub/_ calls)\n\nOptional parameters:\n\n * _callback_ - only for GET listing requests ( _/1/list_ ). JSONP-ready\n\nStarting the web API (it's Sinatra (means Rack) application) on _port 8080_:\n\n    $ cd collecta-xmpp/\n    $ rackup -p 8080\n\nExample command-line usage:\n\n    // me@jabber.org  will recieve results from the 'iphone'  and 'mac category:story' searches\n    $ curl -X POST -d'sig=97...' -d'jid=me@jabber.org' -d'q=iphone' http://example.com/1/sub/\n    $ curl -X POST -d'sig=97...' -d'jid=me@jabber.org' -d'q=\"mac category:story\"' http://example.com/1/sub/\n    // to which quieries is subscribed me@jabber.org\n    $ curl -v \"http://example.com/1/list?jid=me@jabber.org\u0026sig=97...\"\n    ...\n    \u003c Content-Type: application/json; charset=utf-8\n    ...\n    [\"iphone\",\"\\\"mac category:story\\\"\"]\n    // unsubscribe from all queries\n    $  curl -X POST -d'sig=97...' -d'jid=me@jabber.org' http://example.com/1/unsub/\n\nThe subscribed JID (_me@jabber.jp_ in the example above) need first to include the _\"bot.jid\"_ JID from the _config.yml_ file \n(_bot@example.com_ in _config.yml.dist_) in his roster and authorize it for messages exchange.\n\n_collecta\\_shell.rb_\n\nSubscribing JIDs to some queries and unsubscription can be done also via a simple command-line shell. This application is independent\nfrom the web API. They does not share their users subscriptions. In both application that relations are kept only in the memory. The\nmain web service need to take care for the saving of that relations.\n\nStarting the shell:\n\n    $ ruby ./collecta_shell.rb \n    \u003e help\n    \"sub JID QUERY - subscribe JID to QUERY\"\n    \"unsub JID     - unsubscribe JID\"\n    \"exit          - exits the app\"\n    \"help          - this help\"\n    \u003e\n\nSubscribe/unsubscribe some JID to/from a query:\n\n    \u003e sub me@jabber.org \"iphone category:story\"\n    \u003e unsub me@jabber.org\n    \u003e exit\n    Finished\n    $\n\n\n\n## ToDo\n\n * ruby gem\n * patched switchboard for command line parameters usage ( _--query iphone --notify \"apple,mac\"_ )\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzh%2Fcollecta-xmpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzh%2Fcollecta-xmpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzh%2Fcollecta-xmpp/lists"}