circle-so 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9168b54a09c87d1ed7adc9abdd8946b030d06e984ecef02b43eb8f201745e2e
+  data.tar.gz: '01888d6cfe6da5d686c47c5ab750a14c628fa025c09dac1445ea0b02d63905f9'
+SHA512:
+  metadata.gz: 5ede5321b909824ba1e0c16167f554fed5f791dd6defe4689678355e4b401fe98ecafbbb02fd23bfb36af500acfe542b17b952bb60c690fffe401d597faeef95
+  data.tar.gz: 41f64f4e5007116a4a552967f0acb701f457d19ff17f1beeb7b0a766f9179b44144e3e5224b8090767d4766f76a67d10ba24eea04aca7d7df1b6f76386aa3967

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.0] - 2026-08-06
+
+- Initial release.
+- Full coverage of the Circle.so Admin API v2 (68 endpoints across 30
+  resources): community, community members, access groups, spaces, space
+  groups, space/space-group membership, posts, comments, events, event
+  attendees, courses (lessons, sections, progress), community segments,
+  member tags, tagged members, topics, forms, flagged contents, invitation
+  links, messages, direct uploads, embeds, images, profile fields, page
+  profile fields, gamification leaderboard, advanced search, chat
+  preferences.
+- Classified errors (`CircleSo::APIError` subclasses) including the
+  404-HTML "wrong path" guard.
+- Three-state token version detection (`CircleSo.detect_token_version`).
+- Zero runtime dependencies.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lawrence Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# circle-so
+
+Zero-dependency Ruby client for the [Circle.so](https://circle.so) Admin API v2 — full coverage of all 68 endpoints ([official docs](https://api.circle.so/)): members, spaces, space groups, access groups, posts, comments, events, courses, segments, tags, and more, with classified errors and token version detection.
+
+> Unofficial. Not affiliated with Circle Internet Services, Inc.
+
+## Installation
+
+```bash
+gem install circle-so
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "circle-so"
+```
+
+Requires Ruby ≥ 3.1. No runtime dependencies (built on `net/http`).
+
+## Quick start
+
+```ruby
+require "circle_so"
+
+client = CircleSo::Client.new(token: ENV["CIRCLE_SO_TOKEN"])
+
+community = client.community.show
+
+# Invite a member (idempotent — re-inviting an existing email does not
+# create a duplicate or re-send the invitation email):
+result = client.community_members.invite(email: "user@example.com", name: "User Name")
+result["community_member"]["id"]
+
+# Access groups (member identified by email, group id in the URL):
+client.access_groups.list
+client.access_groups.add_member(group_id, email: "user@example.com")
+client.access_groups.remove_member(group_id, email: "user@example.com")
+
+# Spaces / space groups (id goes in the request BODY, even for DELETE):
+client.space_members.add(space_id: 123, email: "user@example.com")
+client.space_group_members.add(space_group_id: 456, email: "user@example.com")
+
+# Posts, events, courses, ...
+client.posts.list(space_id: 123)
+client.events.create(name: "Launch party", space_id: 123)
+client.course_lessons.update_progress(lesson_id: 1, user_email: "user@example.com")
+```
+
+All responses are parsed JSON (`Hash`/`Array` with string keys), exactly as Circle returns them.
+
+## Resources
+
+Every Admin API v2 endpoint is covered:
+
+| `client.` … | Methods |
+|---|---|
+| `access_groups` | `list`, `create`, `update`, `archive`, `unarchive`, `members`, `member`, `add_member`, `remove_member` |
+| `chat_preferences` | `update` |
+| `comments` | `list`, `create`, `show`, `delete` |
+| `community` | `show`, `update` |
+| `community_members` | `list`, `search`, `show`, `update`, `invite`/`create`, `deactivate`, `delete`, `ban`, `access_groups`, `spaces` |
+| `community_segments` | `list`, `create`, `update`, `delete`, `duplicate` |
+| `course_lessons` | `list`, `create`, `show`, `update`, `delete`, `update_progress` |
+| `course_sections` | `list`, `create`, `show`, `update`, `delete` |
+| `direct_uploads` | `create` |
+| `embeds` | `create`, `show` |
+| `event_attendees` | `list`, `add`, `remove` |
+| `events` | `list`, `create`, `show`, `update`, `delete`, `duplicate` |
+| `flagged_contents` | `list`, `create` |
+| `forms` | `list`, `show`, `update`, `delete`, `duplicate` |
+| `gamification` | `leaderboard` |
+| `images` | `create_post`, `delete_post`, `duplicate_post` |
+| `invitation_links` | `list`, `delete`, `revoke` |
+| `member_tags` | `list`, `create`, `show`, `update`, `delete` |
+| `messages` | `create` |
+| `page_profile_fields` | `list` |
+| `posts` | `list`, `create`, `show`, `update`, `delete`, `summary`, `unfollow` |
+| `profile_fields` | `list`, `archive`, `unarchive` |
+| `search` | `advanced` |
+| `space_group_members` | `list`, `show`, `add`, `remove` |
+| `space_groups` | `list`, `create`, `show`, `update`, `delete` |
+| `space_members` | `list`, `show`, `add`, `remove` |
+| `spaces` | `list`, `create`, `show`, `update`, `delete`, `ai_summaries` |
+| `tagged_members` | `list`, `show`, `add`, `remove` |
+| `topics` | `list`, `create`, `show`, `update`, `delete` |
+
+List endpoints accept query params as keyword arguments (`page:`, `per_page:`, filters). Create/update endpoints accept the request body as keyword arguments. There is also a low-level escape hatch: `client.get(path, params)`, `client.post(path, body)`, etc.
+
+## Error handling
+
+Non-2xx responses raise a subclass of `CircleSo::APIError` with a classified `kind`, the HTTP `status`, and the parsed response `body`:
+
+| class | kind | meaning |
+|---|---|---|
+| `CircleSo::UnauthorizedError` | `:unauthorized` | 401 — wrong/invalid token (or a v1 token on the v2 API) |
+| `CircleSo::ForbiddenError` | `:forbidden` | 403 — plan no longer allows the endpoint |
+| `CircleSo::NotFoundError` | `:not_found` | 404 with a JSON body — missing record/param |
+| `CircleSo::WrongPathError` | `:wrong_path` | 404 with an **HTML** body — the route does not exist (bug guard) |
+| `CircleSo::RateLimitedError` | `:rate_limited` | 429 |
+| `CircleSo::ServerError` | `:server_error` | 5xx |
+
+```ruby
+begin
+  client.access_groups.add_member(group_id, email: email)
+rescue CircleSo::UnauthorizedError
+  # pause syncing, prompt the user to re-connect
+rescue CircleSo::APIError => e
+  logger.error("Circle #{e.status} (#{e.kind}): #{e.message}")
+end
+```
+
+The `wrong_path` distinction matters: Circle returns 404 **HTML** for routes that don't exist and 404 **JSON** for missing records. The client tells them apart via `Content-Type` so a typo'd endpoint doesn't masquerade as "record not found".
+
+## Token version detection
+
+Circle issues v1 (Professional plan) and v2 (Business plan) admin tokens that look identical. A v1 token on the v2 API returns a plain 401, so use the three-state probe to give users an actionable error:
+
+```ruby
+CircleSo.detect_token_version(token) # => :v2, :v1, or :invalid
+```
+
+## API quirks this client encodes
+
+Learned from a live integration (the test fixtures under `spec/fixtures` were captured against the real API):
+
+- **Asymmetric membership endpoints.** Access groups take the group id in the URL and the member's *email* in the body (`POST /access_groups/:id/community_members`). Spaces and space groups instead use flat endpoints (`/space_members`, `/space_group_members`) with the id in the body — even for `DELETE`.
+- **Members are keyed by email**, not member id, for all membership operations.
+- **Adds/removes are idempotent.** Re-adding returns the same success response; you can apply a full expected set without querying current state first.
+- **Space group membership cascades** to all spaces inside the group.
+- **First `invite` sends Circle's invitation email**; subsequent calls for the same email are no-ops (the response message says "already a member").
+- **`course_lessons` update uses `PATCH`** while every other update uses `PUT`; `tagged_members.remove` identifies the record via query params.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec   # runs the suite with 100% line-coverage enforcement
+```
+
+Tests stub Circle at the network boundary with [WebMock](https://github.com/bblimke/webmock), replaying real response bodies captured from the live Admin API — no credentials needed, fully deterministic.
+
+## License
+
+MIT

data/lib/circle-so.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Shim so both `require "circle-so"` (the gem name) and `require "circle_so"`
+# work.
+require_relative "circle_so"

data/lib/circle_so/client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module CircleSo
+  # HTTP client for the Circle.so Admin API v2.
+  #
+  #   client = CircleSo::Client.new(token: ENV["CIRCLE_SO_TOKEN"])
+  #   client.community.show
+  #   client.community_members.invite(email: "user@example.com")
+  #
+  # Zero runtime dependencies — built on Net::HTTP. All responses are parsed
+  # JSON (Hash/Array with string keys). Non-2xx responses raise a subclass of
+  # CircleSo::APIError (see errors.rb for the classification).
+  class Client
+    BASE_URL = "https://app.circle.so/api/admin/v2"
+
+    attr_reader :base_url
+
+    def initialize(token:, base_url: BASE_URL, open_timeout: 10, read_timeout: 60)
+      raise ArgumentError, "token is required" if token.nil? || token.empty?
+
+      @token = token
+      @base_url = base_url.chomp("/")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # -- resources ----------------------------------------------------------
+
+    def access_groups = @access_groups ||= Resources::AccessGroups.new(self)
+    def chat_preferences = @chat_preferences ||= Resources::ChatPreferences.new(self)
+    def comments = @comments ||= Resources::Comments.new(self)
+    def community = @community ||= Resources::Community.new(self)
+    def community_members = @community_members ||= Resources::CommunityMembers.new(self)
+    def community_segments = @community_segments ||= Resources::CommunitySegments.new(self)
+    def course_lessons = @course_lessons ||= Resources::CourseLessons.new(self)
+    def course_sections = @course_sections ||= Resources::CourseSections.new(self)
+    def direct_uploads = @direct_uploads ||= Resources::DirectUploads.new(self)
+    def embeds = @embeds ||= Resources::Embeds.new(self)
+    def event_attendees = @event_attendees ||= Resources::EventAttendees.new(self)
+    def events = @events ||= Resources::Events.new(self)
+    def flagged_contents = @flagged_contents ||= Resources::FlaggedContents.new(self)
+    def forms = @forms ||= Resources::Forms.new(self)
+    def gamification = @gamification ||= Resources::Gamification.new(self)
+    def images = @images ||= Resources::Images.new(self)
+    def invitation_links = @invitation_links ||= Resources::InvitationLinks.new(self)
+    def member_tags = @member_tags ||= Resources::MemberTags.new(self)
+    def messages = @messages ||= Resources::Messages.new(self)
+    def page_profile_fields = @page_profile_fields ||= Resources::PageProfileFields.new(self)
+    def posts = @posts ||= Resources::Posts.new(self)
+    def profile_fields = @profile_fields ||= Resources::ProfileFields.new(self)
+    def search = @search ||= Resources::Search.new(self)
+    def space_group_members = @space_group_members ||= Resources::SpaceGroupMembers.new(self)
+    def space_groups = @space_groups ||= Resources::SpaceGroups.new(self)
+    def space_members = @space_members ||= Resources::SpaceMembers.new(self)
+    def spaces = @spaces ||= Resources::Spaces.new(self)
+    def tagged_members = @tagged_members ||= Resources::TaggedMembers.new(self)
+    def topics = @topics ||= Resources::Topics.new(self)
+
+    # -- low-level requests (public escape hatch) ---------------------------
+
+    def get(path, params = {}) = request(Net::HTTP::Get, path, params: params)
+    def post(path, body = nil, params = {}) = request(Net::HTTP::Post, path, body: body, params: params)
+    def put(path, body = nil, params = {}) = request(Net::HTTP::Put, path, body: body, params: params)
+    def patch(path, body = nil, params = {}) = request(Net::HTTP::Patch, path, body: body, params: params)
+    def delete(path, body = nil, params = {}) = request(Net::HTTP::Delete, path, body: body, params: params)
+
+    private
+
+    def request(verb, path, params: {}, body: nil)
+      uri = build_uri(path, params)
+      req = verb.new(uri)
+      req["Authorization"] = "Bearer #{@token}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "circle-so ruby gem #{CircleSo::VERSION}"
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      res = http_for(uri).request(req)
+      handle_response(res, verb, path)
+    end
+
+    def build_uri(path, params)
+      uri = URI.parse("#{@base_url}#{path}")
+      compact = params.reject { |_k, v| v.nil? }
+      uri.query = [uri.query, URI.encode_www_form(compact)].compact.reject(&:empty?).join("&") unless compact.empty?
+      uri
+    end
+
+    def http_for(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http
+    end
+
+    def handle_response(res, verb, path)
+      status = res.code.to_i
+      json = json_response?(res)
+      parsed = json ? parse_json(res.body) : res.body
+
+      return parsed if (200..299).cover?(status)
+
+      # Circle returns 404 with an HTML body when the route does not exist
+      # (vs 404 JSON for a missing record) — surface that as a distinct error
+      # so a typo'd endpoint doesn't masquerade as "record not found".
+      method_name = verb.name.split("::").last.upcase
+      if status == 404 && !json
+        raise WrongPathError.new(
+          "Circle returned 404 HTML for #{method_name} #{path} (route does not exist)",
+          status: 404, body: res.body, kind: :wrong_path
+        )
+      end
+
+      message = (parsed.is_a?(Hash) && parsed["message"]) || "#{method_name} #{path} failed with status #{status}"
+      klass, kind = classify_status(status)
+      raise klass.new(message, status: status, body: parsed, kind: kind)
+    end
+
+    def json_response?(res)
+      (res["content-type"] || "").include?("application/json")
+    end
+
+    def parse_json(body)
+      body.nil? || body.empty? ? nil : JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def classify_status(status)
+      case status
+      when 401 then [UnauthorizedError, :unauthorized]
+      when 403 then [ForbiddenError, :forbidden]
+      when 404 then [NotFoundError, :not_found]
+      when 429 then [RateLimitedError, :rate_limited]
+      when 500..599 then [ServerError, :server_error]
+      else [APIError, :unknown]
+      end
+    end
+  end
+end

data/lib/circle_so/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CircleSo
+  class Error < StandardError; end
+
+  # Raised for any non-2xx response from the Circle API. Carries the HTTP
+  # status, the parsed response body (Hash when JSON, String otherwise), and
+  # a classification kind mirroring the status:
+  #
+  #   :unauthorized  401 — wrong/invalid token (or a v1 token on the v2 API)
+  #   :forbidden     403 — plan no longer allows the endpoint
+  #   :not_found     404 with a JSON body — missing record/param
+  #   :wrong_path    404 with an HTML body — the route does not exist
+  #   :rate_limited  429
+  #   :server_error  5xx
+  #   :unknown       anything else
+  class APIError < Error
+    attr_reader :status, :body, :kind
+
+    def initialize(message, status:, body: nil, kind: :unknown)
+      super(message)
+      @status = status
+      @body = body
+      @kind = kind
+    end
+  end
+
+  class UnauthorizedError < APIError; end
+  class ForbiddenError < APIError; end
+  class NotFoundError < APIError; end
+
+  # Circle returns 404 with an HTML body when the route itself does not exist
+  # (as opposed to 404 JSON for a missing record). Getting this error means
+  # the request hit a non-existent endpoint — a bug, not missing data.
+  class WrongPathError < APIError; end
+
+  class RateLimitedError < APIError; end
+  class ServerError < APIError; end
+end

data/lib/circle_so/resources/access_groups.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class AccessGroups < Base
+      def list(**params) = client.get("/access_groups", params)
+      def create(**attrs) = client.post("/access_groups", attrs)
+      def update(id, **attrs) = client.put("/access_groups/#{id}", attrs)
+      # DELETE archives the access group (Circle keeps the record).
+      def archive(id) = client.delete("/access_groups/#{id}")
+      def unarchive(id) = client.patch("/access_groups/#{id}/unarchive")
+
+      # Membership: the group id goes in the URL, the member is identified by
+      # email (not member id) in the body/query.
+      def members(access_group_id, **params) = client.get("/access_groups/#{access_group_id}/community_members", params)
+      def member(access_group_id, email:) = client.get("/access_groups/#{access_group_id}/community_member", {email: email})
+      def add_member(access_group_id, email:, **attrs) = client.post("/access_groups/#{access_group_id}/community_members", {email: email, **attrs})
+      def remove_member(access_group_id, email:) = client.delete("/access_groups/#{access_group_id}/community_members", {email: email})
+    end
+  end
+end

data/lib/circle_so/resources/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+    end
+  end
+end

data/lib/circle_so/resources/chat_preferences.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class ChatPreferences < Base
+      def update(**attrs) = client.put("/chat_preferences", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/comments.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Comments < Base
+      def list(**params) = client.get("/comments", params)
+      def create(**attrs) = client.post("/comments", attrs)
+      def show(id) = client.get("/comments/#{id}")
+      def delete(id) = client.delete("/comments/#{id}")
+    end
+  end
+end

data/lib/circle_so/resources/community.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Community < Base
+      def show = client.get("/community")
+      def update(**attrs) = client.put("/community", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/community_members.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class CommunityMembers < Base
+      def list(**params) = client.get("/community_members", params)
+      def search(**params) = client.get("/community_members/search", params)
+      def show(id) = client.get("/community_members/#{id}")
+      def update(id, **attrs) = client.put("/community_members/#{id}", attrs)
+
+      # Create/invite a member by email. Idempotent: re-calling for an
+      # existing email returns the same member (no duplicate, no re-sent
+      # invitation email). The response "message" says "already a member"
+      # in that case. First creation triggers Circle's invitation email.
+      def invite(email:, **attrs) = client.post("/community_members", {email: email, **attrs})
+      alias_method :create, :invite
+
+      # Deactivate the member (removes community access, keeps the record).
+      def deactivate(id) = client.delete("/community_members/#{id}")
+      # Permanently delete the member. Note: Circle models this as a PUT.
+      def delete(id) = client.put("/community_members/#{id}/delete_member")
+      def ban(id) = client.put("/community_members/#{id}/ban_member")
+
+      # Access groups this member belongs to.
+      def access_groups(id, **params) = client.get("/community_members/#{id}/access_groups", params)
+
+      # Spaces a member belongs to. Filter with community_member_id: or
+      # user_email: (query params).
+      def spaces(**params) = client.get("/community_member_spaces", params)
+    end
+  end
+end

data/lib/circle_so/resources/community_segments.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class CommunitySegments < Base
+      def list(**params) = client.get("/community_segments", params)
+      def create(**attrs) = client.post("/community_segments", attrs)
+      def update(id, **attrs) = client.put("/community_segments/#{id}", attrs)
+      def delete(id) = client.delete("/community_segments/#{id}")
+      def duplicate(id) = client.post("/community_segments/#{id}/duplicate")
+    end
+  end
+end

data/lib/circle_so/resources/course_lessons.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class CourseLessons < Base
+      def list(**params) = client.get("/course_lessons", params)
+      def create(**attrs) = client.post("/course_lessons", attrs)
+      def show(id) = client.get("/course_lessons/#{id}")
+      # Note: Circle uses PATCH here (course sections use PUT).
+      def update(id, **attrs) = client.patch("/course_lessons/#{id}", attrs)
+      def delete(id) = client.delete("/course_lessons/#{id}")
+
+      def update_progress(**attrs) = client.put("/course_lesson_progress", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/course_sections.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class CourseSections < Base
+      def list(**params) = client.get("/course_sections", params)
+      def create(**attrs) = client.post("/course_sections", attrs)
+      def show(id) = client.get("/course_sections/#{id}")
+      def update(id, **attrs) = client.put("/course_sections/#{id}", attrs)
+      def delete(id) = client.delete("/course_sections/#{id}")
+    end
+  end
+end

data/lib/circle_so/resources/direct_uploads.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class DirectUploads < Base
+      def create(**attrs) = client.post("/direct_uploads", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/embeds.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Embeds < Base
+      def create(**attrs) = client.post("/embeds", attrs)
+      def show(sgid) = client.get("/embeds/#{sgid}")
+    end
+  end
+end

data/lib/circle_so/resources/event_attendees.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class EventAttendees < Base
+      def list(**params) = client.get("/event_attendees", params)
+      def add(**attrs) = client.post("/event_attendees", attrs)
+      def remove(**attrs) = client.delete("/event_attendees", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/events.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Events < Base
+      def list(**params) = client.get("/events", params)
+      def create(**attrs) = client.post("/events", attrs)
+      def show(id) = client.get("/events/#{id}")
+      def update(id, **attrs) = client.put("/events/#{id}", attrs)
+      def delete(id) = client.delete("/events/#{id}")
+      def duplicate(id, space_id:, **attrs) = client.post("/spaces/#{space_id}/events/#{id}/duplicate", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/flagged_contents.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class FlaggedContents < Base
+      def list(**params) = client.get("/flagged_contents", params)
+      def create(**attrs) = client.post("/flagged_contents", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/forms.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Forms < Base
+      def list(**params) = client.get("/forms", params)
+      def show(id) = client.get("/forms/#{id}")
+      def update(id, **attrs) = client.put("/forms/#{id}", attrs)
+      def delete(id) = client.delete("/forms/#{id}")
+      def duplicate(id) = client.post("/forms/#{id}/duplicate")
+    end
+  end
+end

data/lib/circle_so/resources/gamification.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Gamification < Base
+      def leaderboard(**params) = client.get("/gamification/leaderboard", params)
+    end
+  end
+end

data/lib/circle_so/resources/images.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    # Image posts inside a space (/spaces/{space_id}/images/posts).
+    class Images < Base
+      def create_post(space_id, **attrs) = client.post("/spaces/#{space_id}/images/posts", attrs)
+      def delete_post(space_id, id) = client.delete("/spaces/#{space_id}/images/posts/#{id}")
+      def duplicate_post(space_id, id) = client.post("/spaces/#{space_id}/images/posts/#{id}/duplicate")
+    end
+  end
+end

data/lib/circle_so/resources/invitation_links.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class InvitationLinks < Base
+      def list(**params) = client.get("/invitation_links", params)
+      def delete(id) = client.delete("/invitation_links/#{id}")
+      def revoke(id) = client.patch("/invitation_links/#{id}/revoke")
+    end
+  end
+end

data/lib/circle_so/resources/member_tags.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class MemberTags < Base
+      def list(**params) = client.get("/member_tags", params)
+      def create(**attrs) = client.post("/member_tags", attrs)
+      def show(id) = client.get("/member_tags/#{id}")
+      def update(id, **attrs) = client.put("/member_tags/#{id}", attrs)
+      def delete(id) = client.delete("/member_tags/#{id}")
+    end
+  end
+end

data/lib/circle_so/resources/messages.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Messages < Base
+      def create(**attrs) = client.post("/messages", attrs)
+    end
+  end
+end

data/lib/circle_so/resources/page_profile_fields.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class PageProfileFields < Base
+      def list(**params) = client.get("/page_profile_fields", params)
+    end
+  end
+end

data/lib/circle_so/resources/posts.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Posts < Base
+      def list(**params) = client.get("/posts", params)
+      def create(**attrs) = client.post("/posts", attrs)
+      def show(id) = client.get("/posts/#{id}")
+      def update(id, **attrs) = client.put("/posts/#{id}", attrs)
+      def delete(id) = client.delete("/posts/#{id}")
+      def summary(post_id) = client.get("/posts/#{post_id}/summary")
+      def unfollow(post_id, community_member_id:) = client.delete("/posts/#{post_id}/post_followers", nil, {community_member_id: community_member_id})
+    end
+  end
+end

data/lib/circle_so/resources/profile_fields.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class ProfileFields < Base
+      def list(**params) = client.get("/profile_fields", params)
+      def archive(id) = client.put("/profile_fields/#{id}/archive")
+      def unarchive(id) = client.put("/profile_fields/#{id}/unarchive")
+    end
+  end
+end

data/lib/circle_so/resources/search.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Search < Base
+      def advanced(query:, **params) = client.get("/advanced_search", {query: query, **params})
+    end
+  end
+end

data/lib/circle_so/resources/space_group_members.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    # Space group membership uses flat endpoints: the space_group_id goes in
+    # the request body (even for DELETE), not the URL. Members are identified
+    # by email. Adding a member to a space group cascades into all its spaces.
+    class SpaceGroupMembers < Base
+      def list(**params) = client.get("/space_group_members", params)
+      def show(space_group_id:, email:) = client.get("/space_group_member", {space_group_id: space_group_id, email: email})
+      def add(space_group_id:, email:, **attrs) = client.post("/space_group_members", {space_group_id: space_group_id, email: email, **attrs})
+      def remove(space_group_id:, email:) = client.delete("/space_group_members", {space_group_id: space_group_id, email: email})
+    end
+  end
+end

data/lib/circle_so/resources/space_groups.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class SpaceGroups < Base
+      def list(**params) = client.get("/space_groups", params)
+      def create(**attrs) = client.post("/space_groups", attrs)
+      def show(id) = client.get("/space_groups/#{id}")
+      def update(id, **attrs) = client.put("/space_groups/#{id}", attrs)
+      def delete(id) = client.delete("/space_groups/#{id}")
+    end
+  end
+end

data/lib/circle_so/resources/space_members.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    # Space membership uses flat endpoints: the space_id goes in the request
+    # body (even for DELETE), not the URL. Members are identified by email.
+    # Adds/removes are idempotent.
+    class SpaceMembers < Base
+      def list(**params) = client.get("/space_members", params)
+      def show(space_id:, email:) = client.get("/space_member", {space_id: space_id, email: email})
+      def add(space_id:, email:, **attrs) = client.post("/space_members", {space_id: space_id, email: email, **attrs})
+      def remove(space_id:, email:) = client.delete("/space_members", {space_id: space_id, email: email})
+    end
+  end
+end

data/lib/circle_so/resources/spaces.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Spaces < Base
+      def list(**params) = client.get("/spaces", params)
+      def create(**attrs) = client.post("/spaces", attrs)
+      def show(id) = client.get("/spaces/#{id}")
+      def update(id, **attrs) = client.put("/spaces/#{id}", attrs)
+      def delete(id) = client.delete("/spaces/#{id}")
+      def ai_summaries(space_id, **params) = client.get("/spaces/#{space_id}/ai_summaries", params)
+    end
+  end
+end

data/lib/circle_so/resources/tagged_members.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class TaggedMembers < Base
+      def list(**params) = client.get("/tagged_members", params)
+      def show(id) = client.get("/tagged_members/#{id}")
+      def add(**attrs) = client.post("/tagged_members", attrs)
+      # Removal identifies the record by query params, not the body.
+      def remove(user_email:, member_tag_id:) = client.delete("/tagged_members", nil, {user_email: user_email, member_tag_id: member_tag_id})
+    end
+  end
+end

data/lib/circle_so/resources/topics.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CircleSo
+  module Resources
+    class Topics < Base
+      def list(**params) = client.get("/topics", params)
+      def create(**attrs) = client.post("/topics", attrs)
+      def show(id) = client.get("/topics/#{id}")
+      def update(id, **attrs) = client.put("/topics/#{id}", attrs)
+      def delete(id) = client.delete("/topics/#{id}")
+    end
+  end
+end

data/lib/circle_so/token.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module CircleSo
+  # Circle issues two admin token types that look identical but hit different
+  # APIs:
+  #
+  #   :v2      Business-plan token — works against /api/admin/v2
+  #   :v1      Professional-plan token — only /api/v1 (no access groups)
+  #   :invalid not a usable token
+  #
+  # A v1 token on a v2 endpoint returns a plain HTTP 401, indistinguishable
+  # from an invalid token — so probe v2 first, then v1, to give users an
+  # actionable three-state answer.
+  module Token
+    BASE_URL_V1 = "https://app.circle.so/api/v1"
+
+    module_function
+
+    def detect_version(token, base_url_v2: Client::BASE_URL, base_url_v1: BASE_URL_V1)
+      return :v2 if probe(base_url_v2, "Bearer #{token}")
+      return :v1 if probe(base_url_v1, "Token #{token}")
+
+      :invalid
+    end
+
+    def probe(base_url, authorization)
+      uri = URI.parse("#{base_url.chomp("/")}/community_members?per_page=1")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      res = http.request(Net::HTTP::Get.new(uri).tap { |r| r["Authorization"] = authorization })
+      (200..299).cover?(res.code.to_i)
+    end
+    private_class_method :probe
+  end
+end

data/lib/circle_so/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CircleSo
+  VERSION = "0.1.0"
+end

data/lib/circle_so.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "circle_so/version"
+require_relative "circle_so/errors"
+require_relative "circle_so/resources/base"
+require_relative "circle_so/resources/access_groups"
+require_relative "circle_so/resources/chat_preferences"
+require_relative "circle_so/resources/comments"
+require_relative "circle_so/resources/community"
+require_relative "circle_so/resources/community_members"
+require_relative "circle_so/resources/community_segments"
+require_relative "circle_so/resources/course_lessons"
+require_relative "circle_so/resources/course_sections"
+require_relative "circle_so/resources/direct_uploads"
+require_relative "circle_so/resources/embeds"
+require_relative "circle_so/resources/event_attendees"
+require_relative "circle_so/resources/events"
+require_relative "circle_so/resources/flagged_contents"
+require_relative "circle_so/resources/forms"
+require_relative "circle_so/resources/gamification"
+require_relative "circle_so/resources/images"
+require_relative "circle_so/resources/invitation_links"
+require_relative "circle_so/resources/member_tags"
+require_relative "circle_so/resources/messages"
+require_relative "circle_so/resources/page_profile_fields"
+require_relative "circle_so/resources/posts"
+require_relative "circle_so/resources/profile_fields"
+require_relative "circle_so/resources/search"
+require_relative "circle_so/resources/space_group_members"
+require_relative "circle_so/resources/space_groups"
+require_relative "circle_so/resources/space_members"
+require_relative "circle_so/resources/spaces"
+require_relative "circle_so/resources/tagged_members"
+require_relative "circle_so/resources/topics"
+require_relative "circle_so/client"
+require_relative "circle_so/token"
+
+module CircleSo
+  # Convenience constructor: CircleSo.client(token: "...")
+  def self.client(**options) = Client.new(**options)
+
+  # Three-state token probe: :v2, :v1, or :invalid. See CircleSo::Token.
+  def self.detect_token_version(token, **options) = Token.detect_version(token, **options)
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: circle-so
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lawrence Lin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Zero-dependency Ruby client for the Circle.so Admin API v2 — members,
+  spaces, space groups, access groups, posts, events, courses and more, with classified
+  errors and token version detection.
+email:
+- lawrence@kaik.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/circle-so.rb
+- lib/circle_so.rb
+- lib/circle_so/client.rb
+- lib/circle_so/errors.rb
+- lib/circle_so/resources/access_groups.rb
+- lib/circle_so/resources/base.rb
+- lib/circle_so/resources/chat_preferences.rb
+- lib/circle_so/resources/comments.rb
+- lib/circle_so/resources/community.rb
+- lib/circle_so/resources/community_members.rb
+- lib/circle_so/resources/community_segments.rb
+- lib/circle_so/resources/course_lessons.rb
+- lib/circle_so/resources/course_sections.rb
+- lib/circle_so/resources/direct_uploads.rb
+- lib/circle_so/resources/embeds.rb
+- lib/circle_so/resources/event_attendees.rb
+- lib/circle_so/resources/events.rb
+- lib/circle_so/resources/flagged_contents.rb
+- lib/circle_so/resources/forms.rb
+- lib/circle_so/resources/gamification.rb
+- lib/circle_so/resources/images.rb
+- lib/circle_so/resources/invitation_links.rb
+- lib/circle_so/resources/member_tags.rb
+- lib/circle_so/resources/messages.rb
+- lib/circle_so/resources/page_profile_fields.rb
+- lib/circle_so/resources/posts.rb
+- lib/circle_so/resources/profile_fields.rb
+- lib/circle_so/resources/search.rb
+- lib/circle_so/resources/space_group_members.rb
+- lib/circle_so/resources/space_groups.rb
+- lib/circle_so/resources/space_members.rb
+- lib/circle_so/resources/spaces.rb
+- lib/circle_so/resources/tagged_members.rb
+- lib/circle_so/resources/topics.rb
+- lib/circle_so/token.rb
+- lib/circle_so/version.rb
+homepage: https://github.com/linyiru/circle-so
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/linyiru/circle-so
+  source_code_uri: https://github.com/linyiru/circle-so
+  changelog_uri: https://github.com/linyiru/circle-so/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/linyiru/circle-so/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Circle.so Admin API v2
+test_files: []