rocksky 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e128365c7e45c3e9853b61446d4f62b3c117aa7a2b523d627b3e28bf37890862
-  data.tar.gz: fce5a199e7b72de73c407ce3015d856ac8c31150e8d1352f5c2573eab8ffdb8c
+  metadata.gz: f5ff00fa4d526c5436fb713d32c4f49f85609263ccf950ea51a2091bec6d8951
+  data.tar.gz: 161fb86cda0ae97b7044a10c9d5a249971143d00d6cf27560500199ebfdcfbfa
 SHA512:
-  metadata.gz: 8e743abeb46fd38a8238166c907064645766e34b1f3e0e40f63b875fbc1e1cb2fe8d1d8cf90960ec52d0078a535b7b7c14baba7a3c90420a1dbda8b0b3a4b919
-  data.tar.gz: d787a2289995372310020770b4849543ec4edd2f0114bafce19c99afde63abb10d9bed5a90e11a76135023a05895adf6438bf05dfcb9cbb53c7311ea7746d586
+  metadata.gz: 4c279685557ce908beb4d7e763a6b4d3a6fd6e55d51158aa518bdeb70189ecec3b22b2367bd0cdcb61e72439a22f73745159b21d64326a02d49f2f6cec608a26
+  data.tar.gz: 8c09668a64234fc5064e50b53e039cbc9ae2d077290cac0dbeb0769f175ae6f24a65f11a7ae039af34d38793dbbb2897283ff23e7978a87e1ce9453d558c5275

data/README.md

@@ -11,6 +11,12 @@ every Rocksky SDK.
 gem install rocksky
 ```
 
+Or in a Gemfile:
+
+```ruby
+gem "rocksky", "~> 0.5"
+```
+
 The gem is pure-Ruby; the native library is fetched from the GitHub release on
 first load and cached (checksum-verified). For a local checkout, build it once:
 
@@ -46,16 +52,63 @@ camelCase keys.
 
 ### Reads — `Rocksky`
 
-`profile(actor, base:)`, `scrobbles(actor, limit:, offset:, base:)`,
+Named reads: `profile(actor, base:)`, `scrobbles(actor, limit:, offset:, base:)`,
 `top_tracks(limit:, offset:, base:)`, `global_stats(base:)`. Every read takes an
 optional `base:` to target a custom AppView.
 
+**Universal escape hatch** — `Rocksky.get(nsid, params, base: nil, token: nil)`
+reaches the *whole* `app.rocksky.*` read catalog and returns the parsed
+Hash/Array. Pass `token:` to send an `Authorization: Bearer` header for
+auth-gated queries.
+
+```ruby
+Rocksky.get("app.rocksky.album.getAlbums", limit: 10)
+Rocksky.get("app.rocksky.album.getAlbumTracks", uri: album_uri)
+Rocksky.get("app.rocksky.graph.getFollows", actor: "alice.bsky.social")
+Rocksky.get("app.rocksky.actor.getActorLovedSongs", actor: "alice.bsky.social")
+Rocksky.get("app.rocksky.stats.getStats")
+Rocksky.get("app.rocksky.charts.getScrobblesChart", token: "…")
+```
+
+**Typed date-window charts** — `top_tracks_interval(limit:, offset:, interval:)`
+and `top_artists_interval(...)`. `interval:` is `:all` or one of
+`[:days, n]` / `[:weeks, n]` / `[:months, n]` / `[:years, n]` /
+`[:range, start, end]`.
+
+```ruby
+Rocksky.top_tracks_interval(limit: 5, interval: [:days, 7])
+Rocksky.top_artists_interval(limit: 5, interval: :all)
+```
+
+**Match** — `Rocksky.match_song(title, artist, mb_id: nil, isrc: nil)` resolves a
+bare title + artist into full canonical metadata.
+
 ### Writes — `Rocksky::Agent`
 
-`Agent.login(session_path, identifier, password, appview:)` → an agent. Then
-`scrobble(track)` (fans out to artist/album/song/scrobble), `like(uri, cid)`,
-`follow(did)`, `shout(subject_uri, subject_cid, message)`, `refresh_session`, and
-`close` (release the native handle).
+`Agent.login(session_path, identifier, password, appview:, dedup_path:)` → an
+agent. Pass `dedup_path:` to enable scrobble dedup + realtime hydration (see
+below). Then `scrobble(track)` (fans out to artist/album/song/scrobble),
+`like(uri, cid)`, `follow(did)`, `shout(subject_uri, subject_cid, message)`,
+`refresh_session`, and `close` (release the native handle).
+
+**Two scrobble paths** — `scrobble(track)` takes full metadata, while
+`scrobble_match(title, artist, album: nil, mb_id: nil, isrc: nil)` matches a bare
+title + artist first, then writes.
+
+```ruby
+agent.scrobble_match("Chaser", "Calibro 35", album: "Jazzploitation")
+```
+
+**Dedup + realtime** — with `dedup_path:` set at login, `agent.sync_repo`
+backfills from the PDS repo and `agent.hydrate_from_jetstream` streams live
+updates, both deduped against the on-disk store.
+
+```ruby
+agent = Rocksky::Agent.login("session.json", "alice.bsky.social", "app-password",
+                             dedup_path: "./dedup")
+agent.sync_repo
+agent.hydrate_from_jetstream
+```
 
 ### Identity hashes
 

data/lib/rocksky/manifest.json

@@ -1,12 +1,12 @@
 {
   "repo": "tsirysndr/rocksky",
-  "tag": "bindings-v0.1.0",
+  "tag": "bindings-v0.2.0",
   "checksums": {
-    "aarch64-apple-darwin": "219b7b12367377f13afba32516102e2f7993f32de5a73bbb8a0194aa88dc343a",
-    "aarch64-linux-gnu": "5da500cd45bdd8cb3d1caa5cbf59c48c7fccbd8ea6fbb2c3f86d069ffc1e163d",
-    "x86_64-apple-darwin": "1c73239d7f8124d53643df68067a82ba88ae3f9ef8a2f692ab59e70f60c58a1a",
-    "x86_64-linux-gnu": "9e651b38e5a1cc1766d4ab14cb0e337c6dc0a3fd0b70a6a6dfe5aee064d806df",
-    "x86_64-unknown-freebsd": "f52e23181f1d8143f067b1b6d9f7318db5dce3a34f22701f94c2857235cacd45",
-    "x86_64-unknown-netbsd": "98ad3408c4c59a8a98a30e5a8531542e3e8479e1fb210761a07c24710b67bb98"
+    "aarch64-apple-darwin": "3fc61d1194d66f58eaea8b82643bbdcd705ab80a626e38975a3c0d66ea14047d",
+    "aarch64-linux-gnu": "4e6f003fb0c45eba7a675b81cc76b084dc770333b2d8c676b2123d19e78f89a0",
+    "x86_64-apple-darwin": "a90563838920ef3575b1af55062e5f1bddcd124ba0d4b9bd50b5639ab6c4ed4e",
+    "x86_64-linux-gnu": "98c2df9ff416fd3f2f0e50e0e48122751ea829f5208f11002ce9fdd85b0fbe5f",
+    "x86_64-unknown-freebsd": "5ad9efc806706ba51cb7f1fe0e678eb97e03e2dd218fec9fe7e7ab29e0efcb68",
+    "x86_64-unknown-netbsd": "f82db46965ea7872085920d37f4a854f7f882e0efa257df9a11dd3e2f7cebf48"
   }
 }

data/lib/rocksky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rocksky
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/rocksky.rb

@@ -26,12 +26,19 @@ module Rocksky
       "char* rocksky_scrobbles(const char*, const char*, unsigned int, unsigned int)",
       "char* rocksky_top_tracks(const char*, unsigned int, unsigned int)",
       "char* rocksky_global_stats(const char*)",
+      "char* rocksky_get(const char*, const char*, const char*, const char*)",
+      "char* rocksky_match_song(const char*, const char*, const char*, const char*, const char*)",
+      "char* rocksky_top_tracks_interval(const char*, unsigned int, unsigned int, const char*, unsigned int, const char*, const char*)",
+      "char* rocksky_top_artists_interval(const char*, unsigned int, unsigned int, const char*, unsigned int, const char*, const char*)",
       "char* rocksky_song_hash(const char*, const char*, const char*)",
       "void rocksky_string_free(void*)",
       "char* rocksky_last_error()",
-      "void* rocksky_agent_login(const char*, const char*, const char*, const char*)",
+      "void* rocksky_agent_login(const char*, const char*, const char*, const char*, const char*)",
       "void rocksky_agent_free(void*)",
       "char* rocksky_agent_scrobble(void*, const char*)",
+      "char* rocksky_agent_scrobble_match(void*, const char*, const char*, const char*, const char*, const char*)",
+      "char* rocksky_agent_sync_repo(void*)",
+      "char* rocksky_agent_hydrate_from_jetstream(void*)",
       "char* rocksky_agent_like(void*, const char*, const char*)",
       "char* rocksky_agent_follow(void*, const char*)",
       "char* rocksky_agent_shout(void*, const char*, const char*, const char*)",
@@ -82,6 +89,53 @@ module Rocksky
     unwrap(C.rocksky_global_stats(base.to_s))
   end
 
+  # Universal read escape hatch — call any app.rocksky.* query by nsid. +params+
+  # is a hash of string params; the whole read-query catalog is reachable here.
+  #
+  #   Rocksky.get("app.rocksky.album.getAlbum", { uri: uri })
+  #   Rocksky.get("app.rocksky.charts.getScrobblesChart", { did: did })
+  # +token+, when given, is sent as an Authorization: Bearer header — needed for
+  # auth-gated queries.
+  def self.get(nsid, params = {}, base: nil, token: nil)
+    unwrap(C.rocksky_get(base.to_s, nsid, JSON.generate(params), token.to_s))
+  end
+
+  # Resolve full canonical metadata for a bare title + artist (matchSong).
+  def self.match_song(title, artist, mb_id: nil, isrc: nil, base: nil)
+    unwrap(C.rocksky_match_song(base.to_s, title, artist, mb_id.to_s, isrc.to_s))
+  end
+
+  # Top tracks chart over a typed date window. +interval+ is +:all+, or a pair
+  # like +[:days, 7]+ / +[:weeks, 4]+ / +[:months, 1]+ / +[:years, 1]+, or
+  # +[:range, start_rfc3339, end_rfc3339]+.
+  #
+  #   Rocksky.top_tracks_interval(limit: 10, interval: [:days, 7])
+  def self.top_tracks_interval(limit: 50, offset: 0, interval: :all, base: nil)
+    unit, n, s, e = interval_parts(interval)
+    unwrap(C.rocksky_top_tracks_interval(base.to_s, limit, offset, unit, n, s, e))
+  end
+
+  # Top artists chart over a typed date window (see .top_tracks_interval).
+  def self.top_artists_interval(limit: 50, offset: 0, interval: :all, base: nil)
+    unit, n, s, e = interval_parts(interval)
+    unwrap(C.rocksky_top_artists_interval(base.to_s, limit, offset, unit, n, s, e))
+  end
+
+  # Normalize an interval into (unit, n, start, end) for the native call.
+  def self.interval_parts(interval)
+    case interval
+    when :all, nil then ["all", 0, "", ""]
+    when Array
+      kind, a, b = interval
+      return ["range", 0, a.to_s, b.to_s] if kind == :range
+
+      [kind.to_s, Integer(a), "", ""]
+    else
+      raise Error, "invalid interval: #{interval.inspect}"
+    end
+  end
+  private_class_method :interval_parts
+
   # Identity hash — identical across every Rocksky SDK.
   def self.song_hash(title, artist, album)
     take_string(C.rocksky_song_hash(title, artist, album))
@@ -92,8 +146,10 @@ module Rocksky
   # Records are passed as Hashes with camelCase keys (title, artist, album,
   # albumArtist, durationMs, …), matching the wire record shape.
   class Agent
-    def self.login(session_path, identifier, password, appview: nil)
-      ptr = C.rocksky_agent_login(session_path, identifier, password, appview.to_s)
+    # +dedup_path+ enables the local dedup index (needed for #sync_repo /
+    # #hydrate_from_jetstream).
+    def self.login(session_path, identifier, password, appview: nil, dedup_path: nil)
+      ptr = C.rocksky_agent_login(session_path, identifier, password, appview.to_s, dedup_path.to_s)
       raise Error, (Rocksky.take_string(C.rocksky_last_error()) || "login failed") if ptr.null?
 
       new(ptr)
@@ -108,6 +164,23 @@ module Rocksky
       Rocksky.unwrap(C.rocksky_agent_scrobble(@ptr, JSON.generate(track)))
     end
 
+    # Scrobble from just a title + artist (album optional, plus optional mb_id /
+    # isrc anchors): resolve full metadata via matchSong, then fan out.
+    def scrobble_match(title, artist, album: nil, mb_id: nil, isrc: nil)
+      Rocksky.unwrap(C.rocksky_agent_scrobble_match(@ptr, title, artist, album.to_s, mb_id.to_s, isrc.to_s))
+    end
+
+    # Download the caller's repo and (re)build the local dedup index (needs a
+    # dedup_path at login). Returns the per-collection counts.
+    def sync_repo
+      Rocksky.unwrap(C.rocksky_agent_sync_repo(@ptr))
+    end
+
+    # Keep the local dedup index hydrated from Jetstream in the background.
+    def hydrate_from_jetstream
+      Rocksky.unwrap(C.rocksky_agent_hydrate_from_jetstream(@ptr))
+    end
+
     def like(uri, cid)
       Rocksky.unwrap(C.rocksky_agent_like(@ptr, uri, cid))
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rocksky
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Rocksky